10000 Document the `make venv` documentation build target by brettcannon · Pull Request #2953 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

Document the make venv documentation build target #2953

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

Closed
wants to merge 7 commits into from
Closed

Document the make venv documentation build target #2953

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7440ae9
Make the directory for the venv be configurable
brettcannon Jul 30, 2017
b4a8111
Update a URL
brettcannon Jul 30, 2017
bdad7bb
Expand on possible Doc venv directory names
brettcannon Jul 30, 2017
d594bd3
Print out where the Doc venv was created
brettcannon Jul 30, 2017
bc606b8
Document the `make venv` target for the docs
brettcannon Jul 30, 2017
58f3915
Put the venv directory back to what it was
brettcannon Jul 31, 2017
c54e41c
Set SPHINXBUILD to use `-m` for greater flexibility
brettcannon Jul 31, 2017
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 @@ -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
Expand Down
10 changes: 6 additions & 4 deletions Doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@

# You can set these variables from the command line.
PYTHON = python3
VENVDIR = env
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's your thinking about changing the name of the venv directory from venv to env? Making the change would introduce a compatibility issue; even though "make venv" wasn't documented, it's likely being used and, besides leaving a stray "venv" directory around, it would also require current doc builders to change their scripts.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've just seen more use of env instead than venv out in the wild is all. I can put it back.

SPHINXBUILD = sphinx-build
PAPER =
SOURCES =
Expand Down Expand Up @@ -103,11 +104,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
$(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
Expand Down Expand Up @@ -153,7 +155,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
49 changes: 26 additions & 23 deletions Doc/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,45 +7,49 @@ available <https://docs.python.org/dev/download.html>`_.

Documentation on authoring Python documentation, including information about
both style and markup, is available in the "`Documenting Python
<https://docs.python.org/devguide/documenting.html>`_" chapter of the
<https://devguide.python.org/documenting/>`_" chapter of the
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/>`_

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alas, this is currently insufficient. The sphinx-build command in the venv won't be found without other Makefile changes (it doesn't fail if you already have sphinx-build installed on your PATH). Since we're going to have tweak this a bit once the blurb support is merged in, suggest for now just adding a shell source command prior to the make html, i.e. . ./env/bin/activate or (. ./venv/bin/activate).

Copy link
Member Author
@brettcannon brettcannon Jul 31, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Price I pay for wrapping this up before rushing out the door. 😞

But I think I found a better solution than having to activate the venv blindly: setting SPHINXBUILD to $(PYTHON) -m sphinx. It's the same as sphinx-build but with the simpler setting of PYTHON being properly supported. Does that work for you, @ned-deily ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know I suggested something similar for blurb. But now I'm not sure that was the best choice. It's more problematic with sphinx-build since existing doc builds may have been depending on using an already installed (e.g. system) sphinx-build and have never bothered before to run the make venv step (and before, even if they did run that step, it wouldn't have made a difference without tweaking PYTHON). With this change, those builds would now fail unless sphinx had happened to be installed in whatever python3 on PATH points to. I don't know how many users this would affect but it's not hypothetical: I ran into this myself. There are several ways around it; I was thinking the most straightforward way might be to play with PATH in the "build" rule; so something like:
PATH=./venv/bin:$PATH sphinx-build

Either that or we need to make sure this is documented as an incompatible change and then maybe only for 3.7?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another possibility would be to make the build rule depend on the venv rule but, as it stands, that causes venv to be run every time you do any doc build.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My worry with the PATH=./$(VENVDIR)/bin:$PATH $(SPHINXBUILD) solution is won't this require being set for anything that might have an entry in bin? And that seems a bit more error-prone long-term than this current approach as I can see forgetting to set PATH in some rule.

I'm fine with this being a Python 3.7-only thing if that doesn't cause you grief in 3.6 releases. But if you would rather have the PATH solution I'm fine with it as well. Just let me know your preference and I'll update the PR.


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 +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 ::

Expand All @@ -109,11 +113,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 <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
0