From e488b82976509e44a25ab2b7bfa91dcee2f52cbc Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:16:23 -0700 Subject: [PATCH 1/9] Make the directory for the venv be configurable --- Doc/Makefile | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/Makefile b/Doc/Makefile index 63bbe1d4d71450..5400e4a998b0f2 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -5,6 +5,7 @@ # You can set these variables from the command line. PYTHON = python3 +VENVDIR = env SPHINXBUILD = sphinx-build BLURB = $(PYTHON) -m blurb PAPER = @@ -118,11 +119,11 @@ 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 dist: rm -rf dist @@ -168,7 +169,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 From 5188abe4337779eb4fe0e41912fb42a007616871 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:27:44 -0700 Subject: [PATCH 2/9] Expand on possible Doc venv directory names --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index ea7abfe55991d6..59206541ee41a7 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 From 7f668eee6f791c8f80d0342e1f6789ab8000f360 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:28:00 -0700 Subject: [PATCH 3/9] Print out where the Doc venv was created --- Doc/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/Makefile b/Doc/Makefile index 5400e4a998b0f2..7a50a56c6e677d 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -124,6 +124,7 @@ clean: venv: $(PYTHON) -m venv $(VENVDIR) ./$(VENVDIR)/bin/python3 -m pip install -U Sphinx + @echo "The venv has been created in the $(VENVDIR) directory" dist: rm -rf dist From a5929bdf999709a8df350666f9f3d16a355ad79b Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:37:23 -0700 Subject: [PATCH 4/9] Document the `make venv` target for the docs --- Doc/README.rst | 45 ++++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/Doc/README.rst b/Doc/README.rst index 9156e7df67218f..7826a756193653 100644 --- a/Doc/README.rst +++ b/Doc/README.rst @@ -14,38 +14,42 @@ 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 `_ -Using make ----------- +The easiest way to install these tools is to create a virtual environment and +install the tools into there. -A Makefile has been prepared so that on Unix, provided you have installed -Sphinx, you can just run :: - make html - -to build the HTML output files. +Using make +---------- -On Windows, we try to emulate the Makefile as closely as possible with a -``make.bat`` file. +To get started on UNIX, you can create a virtual environment with the command :: -To use a Python interpreter that's not called ``python``, use the standard -way to set Makefile variables, using e.g. :: + make venv - make html PYTHON=python3 +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:: -On Windows, set the PYTHON environment variable instead. + make html PYTHON=./env/bin/python -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 +100,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 +116,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. From 955f6697c62016fff0465b509dd5dc60e8996028 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 31 Jul 2017 10:18:44 -0700 Subject: [PATCH 5/9] Put the venv directory back to what it was --- Doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/Makefile b/Doc/Makefile index 7a50a56c6e677d..9548e4311e3887 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -5,7 +5,7 @@ # You can set these variables from the command line. PYTHON = python3 -VENVDIR = env +VENVDIR = venv SPHINXBUILD = sphinx-build BLURB = $(PYTHON) -m blurb PAPER = From 2e558d43e95d24adbe69e0c31aba1f0326557553 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 31 Jul 2017 10:36:53 -0700 Subject: [PATCH 6/9] Set SPHINXBUILD to use `-m` for greater flexibility --- Doc/Makefile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/Makefile b/Doc/Makefile index 9548e4311e3887..81debb0661400b 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -6,8 +6,7 @@ # You can set these variables from the command line. PYTHON = python3 VENVDIR = venv -SPHINXBUILD = sphinx-build -BLURB = $(PYTHON) -m blurb +SPHINXBUILD = $(PYTHON) -m sphinx PAPER = SOURCES = DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) From c8365f9925223cce63e64cc69157ba4974e61e38 Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Thu, 7 Sep 2017 14:10:18 -0700 Subject: [PATCH 7/9] Merge rest of current blurb support --- Doc/Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/Makefile b/Doc/Makefile index 81debb0661400b..994faa945f5e6c 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -7,6 +7,7 @@ PYTHON = python3 VENVDIR = venv SPHINXBUILD = $(PYTHON) -m sphinx +BLURB = $(PYTHON) -m blurb PAPER = SOURCES = DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) @@ -122,7 +123,7 @@ clean: venv: $(PYTHON) -m venv $(VENVDIR) - ./$(VENVDIR)/bin/python3 -m pip install -U Sphinx + ./$(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb @echo "The venv has been created in the $(VENVDIR) directory" dist: From 860b3b36d834ddb2a0738a3dc8e1650fa89bcf86 Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Thu, 7 Sep 2017 15:58:42 -0700 Subject: [PATCH 8/9] Allow sphinx-build and blurb to be found on PATH if venv not present --- Doc/Makefile | 8 ++++---- Doc/README.rst | 4 ++++ 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/Doc/Makefile b/Doc/Makefile index 994faa945f5e6c..307d1e0e7de10b 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -5,9 +5,9 @@ # You can set these variables from the command line. PYTHON = python3 -VENVDIR = venv -SPHINXBUILD = $(PYTHON) -m sphinx -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) @@ -123,7 +123,7 @@ clean: venv: $(PYTHON) -m venv $(VENVDIR) - ./$(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb + $(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb @echo "The venv has been created in the $(VENVDIR) directory" dist: diff --git a/Doc/README.rst b/Doc/README.rst index 7826a756193653..5a1cb30ca6b1db 100644 --- a/Doc/README.rst +++ b/Doc/README.rst @@ -39,6 +39,10 @@ build the HTML output files:: make html PYTHON=./env/bin/python +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. If you need to specify the Python interpreter to use, set the PYTHON environment variable instead. From 1f3dcee0c0510e84182f687c28f6dfb833c16f9a Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Thu, 7 Sep 2017 16:11:51 -0700 Subject: [PATCH 9/9] "make html" no longer needs PYTHON= --- Doc/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/README.rst b/Doc/README.rst index 5a1cb30ca6b1db..a29d1f3a708a43 100644 --- a/Doc/README.rst +++ b/Doc/README.rst @@ -37,7 +37,7 @@ 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 PYTHON=./env/bin/python + 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