Skip to content

bpo-30487: revert automatically create a venv and install Sphinx whe… #4592

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
ned-deily merged 1 commit into from
Nov 27, 2017
Merged

bpo-30487: revert automatically create a venv and install Sphinx whe… #4592

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
2 changes: 1 addition & 1 deletion .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ matrix:
# (Updating the version is fine as long as no warnings are raised by doing so.)
- python -m pip install sphinx~=1.6.1 blurb
script:
- make check suspicious html SPHINXBUILD="sphinx-build" SPHINXOPTS="-q -W -j4"
- make check suspicious html SPHINXOPTS="-q -W -j4"
- os: linux
language: c
compiler: gcc
Expand Down
12 changes: 5 additions & 7 deletions Doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_elements.papersize=$(PA

.PHONY: help build html htmlhelp latex text changes linkcheck \
suspicious coverage doctest pydoc-topics htmlview clean dist check serve \
autobuild-dev autobuild-stable
autobuild-dev autobuild-stable venv

help:
@echo "Please use \`make <target>' where <target> is one of"
Expand All @@ -39,7 +39,7 @@ help:
@echo " check to run a check for frequent markup errors"
@echo " serve to serve the documentation on the localhost (8000)"

build: venv
build:
-mkdir -p build
# Look first for a Misc/NEWS file (building from a source release tarball
# or old repo) and use that, otherwise look for a Misc/NEWS.d directory
Expand Down Expand Up @@ -122,11 +122,9 @@ clean:
-rm -rf build/* $(VENVDIR)/*

venv:
@if [ "$(SPHINXBUILD)" == "PATH=$(VENVDIR)/bin:$$PATH sphinx-build" ]; then \
$(PYTHON) -m venv $(VENVDIR); \
echo "A virtual environment for Docs has been made in the $(VENVDIR) directory"; \
$(VENVDIR)/bin/python3 -m pip install Sphinx blurb; \
fi
$(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
39 changes: 16 additions & 23 deletions Doc/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,21 @@ tree but are maintained separately and are available from
* `Sphinx <https://pypi.org/project/Sphinx/>`_
* `blurb <https://pypi.org/project/blurb/>`_

You could manually create a virtual environment and install them, but there is
a ``Makefile`` already set up to do this for you, as long as you have a working
Python 3 interpreter available.
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), after you change into the
``Doc/`` directory you can simply run ::
To get started on UNIX, you can create a virtual environment with the command ::

make venv

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

Expand All @@ -39,17 +44,8 @@ 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 ``python3``, use the standard
way to set Makefile variables, using e.g. ::

make html PYTHON=python

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:

Expand Down Expand Up @@ -108,14 +104,11 @@ Available make targets are:
Without make
------------

Install the Sphinx package and its dependencies from PyPI. In this situation,
you'll have to create a virtual environment manually, and install Sphinx into
it. Change into the ``Doc`` directory and run ::
First, install the tool dependencies from PyPI.

Then, from the ``Doc`` directory, run ::

$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ pip install Sphinx
(venv) $ sphinx-build -b<builder> . build/<builder>
sphinx-build -b<builder> . build/<builder>

where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
see the make targets above).
Expand Down