Docs: Create venv if missing

[hugovk]

Problem

I started getting this error:

$ make -C Doc clean
rm -rf ./venv
rm -rf build/*
$ make -C Doc html
mkdir -p build
Building NEWS from Misc/NEWS.d with blurb
PATH=./venv/bin:$PATH sphinx-build -b html -d build/doctrees  -j auto  -W . build/html
Running Sphinx v5.1.1
making output directory... done

Theme error:
no theme named 'python_docs_theme' found (missing theme.conf?)
make: *** [build] Error 2

That's because I have no venv so it can't find the theme.

The problem is we have this, which looks for Sphinx in the venv or $PATH:

SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build

And in my case it's finding it in my $PATH, so this guard passes:

https://github.com/python/cpython/blob/b863b9cd4b8681cf5fff5f121837a1039045783f/Doc/Makefile#L55

But I don't get this warning:

https://github.com/python/cpython/blob/b863b9cd4b8681cf5fff5f121837a1039045783f/Doc/Makefile#L65-L66

Fix

Two things (aka let's do it like the devguide)

1. let's just use the tools in the venv, not $PATH (to make the guard fail, and show the warning):

https://github.com/python/devguide/blob/05f6d0c8d09bd757440e0346190dbd62e06c7251/Makefile#L9-L10

2. and add ensure-venv target that will install the venv if the venv dir is missing (to avoid the warning in the first place):

https://github.com/python/devguide/blob/05f6d0c8d09bd757440e0346190dbd62e06c7251/Makefile#L58-L64

Bonus

Whilst we're changing Docs/Makefile, PR https://github.com/python/cpython/pull/98189 recently fixed some missing .PHONY targets. 👍

I expect missing .PHONY targets will happen again, because it's normal to copy/paste a target, and forget (or not know) to update the long .PHONY line right at the top.

Let's do as @zware suggested and define them right next to each target: https://github.com/python/cpython/pull/98189#issuecomment-1276664528

We do this at Pillow and at work, it helps a lot. (I'll add it to the devguide and PEPs too.)

[zware]

We've been down this road before and it was either not accepted or shortly reverted, though I don't remember why. There is some history to dig up and review here, though past rejection doesn't necessarily mean we must still stick to the status quo.

[JelleZijlstra]

See #27635 and issues #88919 and #88986. Because of a similar change we ended up with Pablo's venv in the distributed 3.10 tarballs.

[hugovk]

Right, so we need to be able to build using pre-downloaded tools not in the venv, so fix 1 and 2 are not needed.

---

We could add a check for other missing tools in this guard:

https://github.com/python/cpython/blob/b863b9cd4b8681cf5fff5f121837a1039045783f/Doc/Makefile#L55-L59

In this case, python_docs_theme was missing, and isn't easy to check for. So I guess "if in doubt, make clean venv applies :)

(I think I've seen a similar problem for another tool that could be checked easily, but I can't remember what it was so I'll address it if it comes up again.)

---

What's left? I think the bonus .PHONY change is still useful. Shall I refactor this PR or make a new, cleaner one?

[hugovk]

What's left? I think the bonus .PHONY change is still useful. Shall I refactor this PR or make a new, cleaner one?

I went for a new, clean PR, please see https://github.com/python/cpython/pull/99396.

And let's close this one, thanks for the background!