bpo-44756: in ./Doc, `make build` depends on `make html` (GH-27403) (GH-27410)

- venv rule is now conditional, and only does anything if $VENVDIR does not exist
- add rule "clean-venv"
(cherry picked from commit d22c876d5ac5fa464337d2e82654b8d87a83cb1b)

Co-authored-by: Jack DeVries <58614260+jdevries3133@users.noreply.github.com>

diff --git a/Doc/Makefile b/Doc/Makefile
index f113dd06539869b46f1629faaa52ad2a70ce0257..ac02bbca971b5be02ba85c61e8f6b055b41183d2 100644 (file)
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -45,7 +45,7 @@ help:
        @echo "  check      to run a check for frequent markup errors"
        @echo "  serve      to serve the documentation on the localhost (8000)"
 
-build:
+build: venv
        -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
@@ -137,14 +137,21 @@ pydoc-topics: build
 htmlview: html
         $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
 
-clean:
-       -rm -rf build/* $(VENVDIR)/*
+clean: clean-venv
+       -rm -rf build/*
+
+clean-venv:
+       rm -rf $(VENVDIR)
 
 venv:
-       $(PYTHON) -m venv $(VENVDIR)
-       $(VENVDIR)/bin/python3 -m pip install -U pip setuptools
-       $(VENVDIR)/bin/python3 -m pip install -r requirements.txt
-       @echo "The venv has been created in the $(VENVDIR) directory"
+       @if [ -d $(VENVDIR) ] ; then \
+               echo "venv already exists"; \
+       else \
+               $(PYTHON) -m venv $(VENVDIR); \
+               $(VENVDIR)/bin/python3 -m pip install -U pip setuptools; \
+               $(VENVDIR)/bin/python3 -m pip install -r requirements.txt; \
+               echo "The venv has been created in the $(VENVDIR) directory"; \
+       fi
 
 dist:
        rm -rf dist

diff --git a/Doc/README.rst b/Doc/README.rst
index 380ea4fa9b26ad338e79bf817b2317227615a044..20c0432ba1d35083f6b2c7a312ab69cf9014676b 100644 (file)
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -28,28 +28,24 @@ install the tools into there.
 Using make
 ----------
 
-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 ``venv`` directory (the default;
-configurable with the VENVDIR variable), you can run the following command to
-build the HTML output files::
+To get started on UNIX, you can create a virtual environment and build
+documentation with the command::
 
   make html
 
-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).
+The virtual environment in the ``venv`` directory will contain all the tools
+necessary to build the documentation.  You can also configure where the virtual
+environment directory will be with the ``VENVDIR`` 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.
+set the PYTHON environment variable.
 
 Available make targets are:
 
-* "clean", which removes all build files.
+* "clean", which removes all build files and the virtual environment.
+
+* "clean-venv", which removes the virtual environment directory.
 
 * "venv", which creates a virtual environment with all necessary tools
   installed.

diff --git a/Misc/NEWS.d/next/Tools-Demos/2021-07-28-00-51-55.bpo-44756.pvAajB.rst b/Misc/NEWS.d/next/Tools-Demos/2021-07-28-00-51-55.bpo-44756.pvAajB.rst
new file mode 100644 (file)
index 0000000..4734f1f
--- /dev/null
+++ b/Misc/NEWS.d/next/Tools-Demos/2021-07-28-00-51-55.bpo-44756.pvAajB.rst
@@ -0,0 +1,6 @@
+In the Makefile for documentation (:file:`Doc/Makefile`), the ``build`` rule
+is dependent on the ``venv`` rule. Therefore, ``html``, ``latex``, and other
+build-dependent rules are also now dependent on ``venv``. The ``venv`` rule
+only performs an action if ``$(VENVDIR)`` does not exist.
+:file:`Doc/README.rst` was updated; most users now only need to type ``make
+html``.