Skip to content

[3.6] bpo-31036: Allow sphinx and blurb to be found automatically (GH-3440) #3441

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 8, 2017
Merged

[3.6] bpo-31036: Allow sphinx and blurb to be found automatically (GH-3440) #3441

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,9 @@
.gdb_history
Doc/build/
Doc/venv/
Doc/.venv/
Doc/env/
Doc/.env/
Include/pydtrace_probes.h
Lib/distutils/command/*.pdb
Lib/lib2to3/*.pickle
Expand Down
14 changes: 8 additions & 6 deletions Doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
47 changes: 27 additions & 20 deletions Doc/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 ::

Expand All @@ -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.
Expand Down