I would expect most of the make targets to automatically create a venv with requirements.txt installed and run in that venv

I don't know what the precedent is here, but I would be wary of doing this -- the user may have a general "documentation" venv, or use an alternate package manager (conda) -- combining the two might cause problems.

I don't understand (1), perhaps as of an ignorance of how things work on Unix -- how would one specify "Python 3, but search PATH for the executable"?

A

I don't have a clear solution for all the cases, other than the most useful thing would be venv-by-default with the option to explicitly not run in a venv. The point is rather moot due to #2402 though.

My make-fu is pretty weak as I'm mostly used to cross-platform tools like tox/nox, but it always did strike me as odd that there was a venv target, but nothing else seemed to directly use it. It seems it should be either integrated or removed.

Like @AA-Turner I'm a little confused about 3., since it just says PYTHON=python3 rather than the mentioned hardcoded path, which I assumed would pick up the active python in the current venv, conda env, etc. I'm guessing I'm missing something here?

For reference, the CPython docs build uses a Makefile:

cd Doc
make venv
make html

https://devguide.python.org/documenting/#building-the-documentation

It also has PYTHON=python3:

https://github.com/python/cpython/blob/8714b6fa27271035dd6dd3514e283f92d669321d/Doc/Makefile#L7

Please see PR #2408 to first create a venv using the Python version supplied to make, and then install and run the tools from within the venv.