diff options
| -rw-r--r-- | Doc/Makefile | 5 | ||||
| -rw-r--r-- | Doc/README.rst | 13 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2021-08-06-19-36-21.bpo-44756.1Ngzon.rst | 3 |
3 files changed, 16 insertions, 5 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index ac02bbc..24528a1 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 20c0432..7e8a27b 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 0000000..ca2e1b9 --- /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. |