From 590665c399fc4aa3c4a9f8e7104d43a02e9f3a0c Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Thu, 7 Sep 2017 17:17:53 -0700 Subject: [PATCH] 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. --- .gitignore | 3 +++ Doc/Makefile | 14 ++++++++------ Doc/README.rst | 49 ++++++++++++++++++++++++++++--------------------- 3 files changed, 39 insertions(+), 27 deletions(-) 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.