bpo-31036: Allow sphinx and blurb to be found automatically (#3440)

Rather than requiring the path to blurb and/or sphinx-build to be specified to the make rule, enhance the Doc/Makefile to look for each first in a virtual environment created by make venv and, if not found, look on the normal process PATH. This allows the Doc/Makefile to take advantage of an installed spinx-build or blurb and, thus, do the right thing most of the time. Also, make the directory for the venv be configurable and document the `make venv` target.

1 files changed, 27 insertions, 20 deletions

diff --git a/Doc/README.rst b/Doc/README.rst
index 9156e7d..a29d1f3 100644
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -14,38 +14,46 @@ developers guide.
 Building the docs
 =================
 
-You need to have `Sphinx <http://sphinx-doc.org/>`_ installed; it is the toolset
-used to build the docs.  It is not included in this tree, but maintained
-separately and `available from PyPI <https://pypi.python.org/pypi/Sphinx>`_.
+The documentation is built with several tools which are not included in this
+tree but are maintained separately and are available from
+`PyPI <https://pypi.org/>`_.
+
+* `Sphinx <https://pypi.org/project/Sphinx/>`_
+* `blurb <https://pypi.org/project/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.
-
-On Windows, we try to emulate the Makefile as closely as possible with a
-``make.bat`` file.
+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::
 
-To use a Python interpreter that's not called ``python``, use the standard
-way to set Makefile variables, using e.g. ::
+  make html
 
-   make html PYTHON=python3
+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, set the PYTHON environment variable instead.
-
-To use a specific sphinx-build (something other than ``sphinx-build``), set
-the SPHINXBUILD variable.
+On Windows, we try to emulate the Makefile as closely as possible with a
+``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 <https://bugs.python.org>`_.
 
-Bugs in the toolset should be reported in the
-`Sphinx bug tracker <https://github.com/sphinx-doc/sphinx/issues>`_.
+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.