Document how sphinx-autobuild can be used for nicer, faster, and better doc writing process

[Mike Edmunds]

CPython's docs Makefile includes an ​htmllive target that's extremely helpful while working on docs. It:

• Builds the docs
• Opens a web browser on the local docs build (like Django's "make htmlview")
• Watches the docs source and rebuilds after any changes
• Hot reloads updated pages

All of this is via ​sphinx-autobuild.

We should borrow that "htmllive" target for Django's docs/Makefile.

(I haven't investigated whether sphinx-autobuild works on Windows. If so, we'd also add it in docs/make.bat.)

[Mike Edmunds]

Note that sphinx-autobuild can be used with the existing docs/Makefile by setting a few variables:

python -m pip install sphinx-autobuild
cd docs
SPHINXBUILD=sphinx-autobuild SPHINXOPTS=--open-browser make dirhtml

You can substitute make html or any other html-like target. Set SPHINXOPTS='--open-browser --delay 0' if you want the browser to open faster.

Something similar should work on Windows with docs/make.bat, which supports the same variables. (Command syntax is left as an exercise for the reader.)

Although "htmllive" and "dirhtmllive" Makefile targets would be nice, that does add a docs dependency on sphinx-autobuild. (Or starts us down the path of installing dependencies on demand, which is what CPython's Makefile does.) We might prefer to just mention using sphinx-autobuild as a tip in the contributor docs.

[Natalia Bidart]

Thank you Mike. I've been using forever SPHINXOPTS="--port 5555" SPHINXBUILD=sphinx-autobuild make html (just because I want my docs in the 5555 port). In all honesty, I'm not sure we should add this one to the Makefile. It requires a new dependency and we are very careful about declaring new dependencies in the project.

I wouldn't object to documenting this nicety, though, in the "writing docs" section. I could accept on that premise, otherwise this is a (friendly) wontfix from my POV.

[Mike Edmunds]

Yeah, I think this would be better as a tip in the docs.

(Can't believe I've been maintaining docs in Sphinx for ~15 years and am just now learning of sphinx-autobuild 🤯)

[Natalia Bidart]

Great, accepting as a docs addition.

[nessita <124304+nessita@…>]

In 9676439:

Fixed #37157 -- Doc'd usage of sphinx-autobuild for documentation auto-reloading.

[Natalia <124304+nessita@…>]

In 5a2a523:

[6.1.x] Fixed #37157 -- Doc'd usage of sphinx-autobuild for documentation auto-reloading.

Backport of 967643959f0a6f5351e4fdeb48cf935d787e4e6a from main.