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.
This commit is contained in:
Ned Deily
GitHub
parent
5a8516701f
commit
590665c399
|
|
@ -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
|
||||
|
|
|
|||
14
Doc/Makefile
14
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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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 <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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue