[Python-checkins] bpo-44756: [docs] revert automated virtual environment creation on `make html` (GH-27635)

[ambv]

https://github.com/python/cpython/commit/55fa87b1ef46bbb9db7612b2dc2dd7fb039d9bc3
commit: 55fa87b1ef46bbb9db7612b2dc2dd7fb039d9bc3
branch: main
author: Łukasz Langa <lukasz at langa.pl>
committer: ambv <lukasz at langa.pl>
date: 2021-08-06T20:13:59+02:00
summary:

bpo-44756: [docs] revert automated virtual environment creation on `make html` (GH-27635)

It turned out to be disruptive for downstream distributors.

files:
A Misc/NEWS.d/next/Documentation/2021-08-06-19-36-21.bpo-44756.1Ngzon.rst
M Doc/Makefile
M Doc/README.rst

diff --git a/Doc/Makefile b/Doc/Makefile
index ac02bbca971b5b..24528a1c4f3269 100644
--- 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: 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
@@ -145,7 +145,8 @@ clean-venv:
 
 venv:
 	@if [ -d $(VENVDIR) ] ; then \
-		echo "venv already exists"; \
+		echo "venv already exists."; \
+		echo "To recreate it, remove it first with \`make clean-venv'."; \
 	else \
 		$(PYTHON) -m venv $(VENVDIR); \
 		$(VENVDIR)/bin/python3 -m pip install -U pip setuptools; \
diff --git a/Doc/README.rst b/Doc/README.rst
index 20c0432ba1d350..7e8a27b4066d87 100644
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -29,13 +29,20 @@ Using make
 ----------
 
 To get started on UNIX, you can create a virtual environment and build
-documentation with the command::
+documentation with the commands::
 
+  make venv
   make html
 
 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.
+necessary to build the documentation downloaded and installed from PyPI.
+If you'd like to create the virtual environment in a different location,
+you can specify it using the ``VENVDIR`` variable.
+
+You can also skip creating the virtual environment altogether, in which case
+the Makefile will 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. If you need to specify the Python interpreter to use,
diff --git a/Misc/NEWS.d/next/Documentation/2021-08-06-19-36-21.bpo-44756.1Ngzon.rst b/Misc/NEWS.d/next/Documentation/2021-08-06-19-36-21.bpo-44756.1Ngzon.rst
new file mode 100644
index 00000000000000..ca2e1b9b53b752
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-08-06-19-36-21.bpo-44756.1Ngzon.rst
@@ -0,0 +1,3 @@
+Reverted automated virtual environment creation on ``make html`` when
+building documentation. It turned out to be disruptive for downstream
+distributors.