Revert "bpo-30487: automatically create a venv and install Sphinx when running make (GH-4346)" (#4592)
Fix breakage documented in bpo-32149.
This reverts commit d8d6b9122134f040cd5a4f15f40f6c9e3386db4d.
diff --git a/Doc/Makefile b/Doc/Makefile
index 69e7e2e..307d1e0 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -17,7 +17,7 @@
.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"
@@ -39,7 +39,7 @@
@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
@@ -122,11 +122,9 @@
-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
diff --git a/Doc/README.rst b/Doc/README.rst
index c0a8d89..a29d1f3 100644
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -21,16 +21,21 @@
* `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
@@ -39,17 +44,8 @@
(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:
@@ -108,14 +104,11 @@
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.
- $ python3 -m venv venv
- $ source venv/bin/activate
- (venv) $ pip install Sphinx
- (venv) $ sphinx-build -b<builder> . build/<builder>
+Then, from the ``Doc`` directory, run ::
+
+ sphinx-build -b<builder> . build/<builder>
where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
see the make targets above).