[2.7] bpo-31036: Allow sphinx and blurb to be found automatically (py…

…thonGH-16638)

Rather than requiring the path to blurb and/or sphinx-build to be specified to the make rule, enhance the Doc/Makefile to look for each first in a virtual environment created by make venv and, if not found, look on the normal process PATH. This allows the Doc/Makefile to take advantage of an installed spinx-build or blurb and, thus, do the right thing most of the time. Also, make the directory for the venv be configurable and document the `make venv` target..
(cherry picked from commit 590665c)

Co-authored-by: Ned Deily <[email protected]>

.gitignore

@@ -16,10 +16,10 @@
 *.profraw
 *.dyn
 Doc/build/
-Doc/tools/docutils/
-Doc/tools/jinja2/
-Doc/tools/pygments/
-Doc/tools/sphinx/
+Doc/venv/
+Doc/.venv/
+Doc/env/
+Doc/.env/
 Lib/lib2to3/*.pickle
 Lib/test/data/*
 Makefile

Doc/Makefile

@@ -5,7 +5,9 @@
 
 # You can set these variables from the command line.
 PYTHON       = python
-SPHINXBUILD  = sphinx-build
+VENVDIR      = ./venv
+SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
+BLURB        = PATH=$(VENVDIR)/bin:$$PATH blurb
 PAPER        =
 SOURCES      =
 DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
@@ -102,7 +104,12 @@ htmlview: html
 	 $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
 
 clean:
-	-rm -rf build/*
+	-rm -rf build/* $(VENVDIR)/*
+
+venv:
+	$(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
@@ -148,7 +155,7 @@ dist:
 	cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
 
 check:
-	$(PYTHON)2 tools/rstlint.py -i tools
+	$(PYTHON)2 tools/rstlint.py -i tools -i $(VENVDIR)
 
 serve:
 	../Tools/scripts/serve.py build/html