bpo-44756: [docs] revert automated virtual environment creation on `m…

…ake html` (pythonGH-27635)

It turned out to be disruptive for downstream distributors.
(cherry picked from commit 55fa87b)

Co-authored-by: Łukasz Langa <lukasz@langa.pl>

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; \

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,

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.