diff options
author | Ned Deily <nad@python.org> | 2017-09-08 00:17:53 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-09-08 00:17:53 (GMT) |
commit | 590665c399fc4aa3c4a9f8e7104d43a02e9f3a0c (patch) | |
tree | a4bc5681706799eb6b457336b510aa0d0200e5d5 /Doc/README.rst | |
parent | 5a8516701f5140c8c989c40e261a4f4e20e8af86 (diff) | |
download | cpython-590665c399fc4aa3c4a9f8e7104d43a02e9f3a0c.zip cpython-590665c399fc4aa3c4a9f8e7104d43a02e9f3a0c.tar.gz cpython-590665c399fc4aa3c4a9f8e7104d43a02e9f3a0c.tar.bz2 |
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.
Diffstat (limited to 'Doc/README.rst')
-rw-r--r-- | Doc/README.rst | 47 |
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. |