diff --git a/.gitignore b/.gitignore
index ea7abfe5599..59206541ee4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,9 @@
.gdb_history
Doc/build/
Doc/venv/
+Doc/.venv/
+Doc/env/
+Doc/.env/
Include/pydtrace_probes.h
Lib/distutils/command/*.pdb
Lib/lib2to3/*.pickle
diff --git a/Doc/Makefile b/Doc/Makefile
index 63bbe1d4d71..307d1e0e7de 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -5,8 +5,9 @@
# You can set these variables from the command line.
PYTHON = python3
-SPHINXBUILD = sphinx-build
-BLURB = $(PYTHON) -m blurb
+VENVDIR = ./venv
+SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
+BLURB = PATH=$(VENVDIR)/bin:$$PATH blurb
PAPER =
SOURCES =
DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py)
@@ -118,11 +119,12 @@ htmlview: html
$(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
clean:
- -rm -rf build/* venv/*
+ -rm -rf build/* $(VENVDIR)/*
venv:
- $(PYTHON) -m venv venv
- ./venv/bin/python3 -m pip install -U Sphinx blurb
+ $(PYTHON) -m venv $(VENVDIR)
+ $(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb
+ @echo "The venv has been created in the $(VENVDIR) directory"
dist:
rm -rf dist
@@ -168,7 +170,7 @@ dist:
cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
check:
- $(PYTHON) tools/rstlint.py -i tools -i venv -i README.rst
+ $(PYTHON) tools/rstlint.py -i tools -i $(VENVDIR) -i README.rst
serve:
../Tools/scripts/serve.py build/html
diff --git a/Doc/README.rst b/Doc/README.rst
index 9156e7df672..a29d1f3a708 100644
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -14,38 +14,46 @@ developers guide.
Building the docs
=================
-You need to have `Sphinx `_ installed; it is the toolset
-used to build the docs. It is not included in this tree, but maintained
-separately and `available from PyPI `_.
+The documentation is built with several tools which are not included in this
+tree but are maintained separately and are available from
+`PyPI `_.
+
+* `Sphinx `_
+* `blurb `_
+
+The easiest way to install these tools is to create a virtual environment and
+install the tools into there.
Using make
----------
-A Makefile has been prepared so that on Unix, provided you have installed
-Sphinx, you can just run ::
+To get started on UNIX, you can create a virtual environment with the command ::
- make html
+ make venv
-to build the HTML output files.
+That will install all the tools necessary to build the documentation. Assuming
+the virtual environment was created in the ``env`` directory (the default;
+configurable with the VENVDIR variable), you can run the following command to
+build the HTML output files::
+
+ make html
+
+By default, if the virtual environment is not created, the Makefile will
+look for instances of sphinxbuild and blurb installed on your process PATH
+(configurable with the SPHINXBUILD and BLURB variables).
On Windows, we try to emulate the Makefile as closely as possible with a
-``make.bat`` file.
-
-To use a Python interpreter that's not called ``python``, use the standard
-way to set Makefile variables, using e.g. ::
-
- make html PYTHON=python3
-
-On Windows, set the PYTHON environment variable instead.
-
-To use a specific sphinx-build (something other than ``sphinx-build``), set
-the SPHINXBUILD variable.
+``make.bat`` file. If you need to specify the Python interpreter to use,
+set the PYTHON environment variable instead.
Available make targets are:
* "clean", which removes all build files.
+* "venv", which creates a virtual environment with all necessary tools
+ installed.
+
* "html", which builds standalone HTML files for offline viewing.
* "htmlview", which re-uses the "html" builder, but then opens the main page
@@ -96,7 +104,7 @@ Available make targets are:
Without make
------------
-Install the Sphinx package and its dependencies from PyPI.
+First, install the tool dependencies from PyPI.
Then, from the ``Doc`` directory, run ::
@@ -112,8 +120,7 @@ Contributing
Bugs in the content should be reported to the
`Python bug tracker `_.
-Bugs in the toolset should be reported in the
-`Sphinx bug tracker `_.
+Bugs in the toolset should be reported to the tools themselves.
You can also send a mail to the Python Documentation Team at docs@python.org,
and we will process your request as soon as possible.