From 7440ae961e0234518bc035a89fd214b371236271 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:16:23 -0700 Subject: [PATCH 1/7] 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 ae59f3294f1c06..ea090a7ed23aa3 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 PAPER = SOURCES = @@ -103,11 +104,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 + $(PYTHON) -m venv $(VENVDIR) + ./$(VENVDIR)/bin/python3 -m pip install -U Sphinx dist: rm -rf dist @@ -153,7 +154,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 b4a81111cd7ce046f510629bf4717ee739ac293c Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:19:23 -0700 Subject: [PATCH 2/7] Update a URL --- Doc/README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/README.rst b/Doc/README.rst index dcd3d6e80ff3c4..9156e7df67218f 100644 --- a/Doc/README.rst +++ b/Doc/README.rst @@ -7,7 +7,7 @@ available `_. Documentation on authoring Python documentation, including information about both style and markup, is available in the "`Documenting Python -`_" chapter of the +`_" chapter of the developers guide. @@ -109,10 +109,10 @@ see the make targets above). Contributing ============ -Bugs in the content should be reported to the +Bugs in the content should be reported to the `Python bug tracker `_. -Bugs in the toolset should be reported in the +Bugs in the toolset should be reported in the `Sphinx bug tracker `_. You can also send a mail to the Python Documentation Team at docs@python.org, From bdad7bb39bb338a46e16033777ba0f1319368da9 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:27:44 -0700 Subject: [PATCH 3/7] 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 d594bd33eabdda5f5fea44120e6720ef4cdc2941 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:28:00 -0700 Subject: [PATCH 4/7] 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 ea090a7ed23aa3..643217d769177a 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -109,6 +109,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 bc606b8db009abbd8d55d2a66006c1776d50283d Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sun, 30 Jul 2017 13:37:23 -0700 Subject: [PATCH 5/7] 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 58f3915edbd9a2a51df710f7a1f4ebc8d1e5f966 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 31 Jul 2017 10:18:44 -0700 Subject: [PATCH 6/7] 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 643217d769177a..7b60f76bdbda71 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 PAPER = SOURCES = From c54e41c94165967a021ff65d76b8b825a183c05e Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 31 Jul 2017 10:36:53 -0700 Subject: [PATCH 7/7] Set SPHINXBUILD to use `-m` for greater flexibility --- Doc/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/Makefile b/Doc/Makefile index 7b60f76bdbda71..c6285a8ef86653 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -6,7 +6,7 @@ # You can set these variables from the command line. PYTHON = python3 VENVDIR = venv -SPHINXBUILD = sphinx-build +SPHINXBUILD = $(PYTHON) -m sphinx PAPER = SOURCES = DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py)