[Python-checkins] Revert "bpo-30487: automatically create a venv and install Sphinx when running make (GH-4346)" (#4592)

[Ned Deily]

https://github.com/python/cpython/commit/122fc136b34e11906466851e77bb6959946467ee
commit: 122fc136b34e11906466851e77bb6959946467ee
branch: master
author: Ned Deily <nad at python.org>
committer: GitHub <noreply at github.com>
date: 2017-11-27T17:07:32-05:00
summary:

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.

files:
M .travis.yml
M Doc/Makefile
M Doc/README.rst

diff --git a/.travis.yml b/.travis.yml
index 4e8be5e0350..c207bd72da2 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -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
diff --git a/Doc/Makefile b/Doc/Makefile
index 69e7e2eecea..307d1e0e7de 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -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"
@@ -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
@@ -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
diff --git a/Doc/README.rst b/Doc/README.rst
index c0a8d89a8c7..a29d1f3a708 100644
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -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
 
@@ -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:
 
@@ -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).