diff options
| -rw-r--r-- | .gitignore | 3 | ||||
| -rw-r--r-- | Doc/Makefile | 14 | ||||
| -rw-r--r-- | Doc/README.rst | 47 |
3 files changed, 38 insertions, 26 deletions
@@ -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 63bbe1d..307d1e0 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 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. |