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

- venv rule is now conditional, and only does anything if $VENVDIR does not exist
- add rule "clean-venv"

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:
+clean: clean-venv
-	-rm -rf build/* $(VENVDIR)/*
+	-rm -rf build/*
+
+clean-venv:
+	rm -rf $(VENVDIR)
 
 venv:
-	$(PYTHON) -m venv $(VENVDIR)
+	@if [ -d $(VENVDIR) ] ; then \
-	$(VENVDIR)/bin/python3 -m pip install -U pip setuptools
+		echo "venv already exists"; \
-	$(VENVDIR)/bin/python3 -m pip install -r requirements.txt
+	else \
-	@echo "The venv has been created in the $(VENVDIR) directory"
+		$(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

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 ::
+To get started on UNIX, you can create a virtual environment and build
-
+documentation 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::
 
   make html
 
-By default, if the virtual environment is not created, the Makefile will
+The virtual environment in the ``venv`` directory will contain all the tools
-look for instances of sphinxbuild and blurb installed on your process PATH
+necessary to build the documentation.  You can also configure where the virtual
-(configurable with the SPHINXBUILD and BLURB variables).
+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.

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``.