[3.11] Docs: Add make htmllive to rebuild and reload HTML files in …

…your browser (GH-111900) (#112023)

Co-authored-by: Hugo van Kemenade <[email protected]>

Doc/Makefile

@@ -22,16 +22,14 @@ PAPEROPT_letter = -D latex_elements.papersize=letterpaper
 ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) -j $(JOBS) \
                 $(SPHINXOPTS) $(SPHINXERRORHANDLING) . build/$(BUILDER) $(SOURCES)
 
-.PHONY: help build html htmlhelp latex text texinfo changes linkcheck \
-	suspicious coverage doctest pydoc-topics htmlview clean dist check serve \
-	autobuild-dev autobuild-stable venv
-
+.PHONY: help
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  clean      to remove build files"
 	@echo "  venv       to create a venv with necessary tools"
 	@echo "  html       to make standalone HTML files"
 	@echo "  htmlview   to open the index page built by the html target in your browser"
+	@echo "  htmllive   to rebuild and reload HTML files in your browser"
 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  text       to make plain text files"
@@ -46,6 +44,7 @@ help:
 	@echo "  suspicious to check for suspicious markup in output text"
 	@echo "  check      to run a check for frequent markup errors"
 
+.PHONY: build
 build:
 	-mkdir -p build
 # Look first for a Misc/NEWS file (building from a source release tarball
@@ -72,45 +71,54 @@ build:
 	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 
+.PHONY: html
 html: BUILDER = html
 html: build
 	@echo "Build finished. The HTML pages are in build/html."
 
+.PHONY: htmlhelp
 htmlhelp: BUILDER = htmlhelp
 htmlhelp: build
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      "build/htmlhelp/pydoc.hhp project file."
 
+.PHONY: latex
 latex: BUILDER = latex
 latex: build
 	@echo "Build finished; the LaTeX files are in build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
+.PHONY: text
 text: BUILDER = text
 text: build
 	@echo "Build finished; the text files are in build/text."
 
+.PHONY: texinfo
 texinfo: BUILDER = texinfo
 texinfo: build
 	@echo "Build finished; the python.texi file is in build/texinfo."
 	@echo "Run \`make info' in that directory to run it through makeinfo."
 
+.PHONY: epub
 epub: BUILDER = epub
 epub: build
 	@echo "Build finished; the epub files are in build/epub."
 
+.PHONY: changes
 changes: BUILDER = changes
 changes: build
 	@echo "The overview file is in build/changes."
 
+.PHONY: linkcheck
 linkcheck: BUILDER = linkcheck
 linkcheck:
 	@$(MAKE) build BUILDER=$(BUILDER) || { \
 	echo "Link check complete; look for any errors in the above output" \
 	     "or in build/$(BUILDER)/output.txt"; \
 	false; }
 
+.PHONY: suspicious
 suspicious: BUILDER = suspicious
 suspicious:
 	@$(MAKE) build BUILDER=$(BUILDER) || { \
@@ -123,31 +131,43 @@ suspicious:
 	@echo "⚠     make check"
 	@echo "⚠ instead."
 
+.PHONY: coverage
 coverage: BUILDER = coverage
 coverage: build
 	@echo "Coverage finished; see c.txt and python.txt in build/coverage"
 
+.PHONY: doctest
 doctest: BUILDER = doctest
 doctest:
 	@$(MAKE) build BUILDER=$(BUILDER) || { \
 	echo "Testing of doctests in the sources finished, look at the" \
 	     "results in build/doctest/output.txt"; \
 	false; }
 
+.PHONY: pydoc-topics
 pydoc-topics: BUILDER = pydoc-topics
 pydoc-topics: build
 	@echo "Building finished; now run this:" \
 	      "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py"
 
+.PHONY: htmlview
 htmlview: html
 	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
 
+.PHONY: htmllive
+htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
+htmllive: SPHINXOPTS = --re-ignore="/venv/"
+htmllive: html
+
+.PHONY: clean
 clean: clean-venv
 	-rm -rf build/*
 
+.PHONY: clean-venv
 clean-venv:
 	rm -rf $(VENVDIR)
 
+.PHONY: venv
 venv:
 	@if [ -d $(VENVDIR) ] ; then \
 		echo "venv already exists."; \
@@ -159,6 +179,7 @@ venv:
 		echo "The venv has been created in the $(VENVDIR) directory"; \
 	fi
 
+.PHONY: dist
 dist:
 	rm -rf dist
 	mkdir -p dist
@@ -213,10 +234,12 @@ dist:
 	rm -r dist/python-$(DISTVERSION)-docs-texinfo
 	rm dist/python-$(DISTVERSION)-docs-texinfo.tar
 
+.PHONY: check
 check: venv
 	$(VENVDIR)/bin/python3 -m pre_commit --version > /dev/null || $(VENVDIR)/bin/python3 -m pip install pre-commit
 	$(VENVDIR)/bin/python3 -m pre_commit run --all-files
 
+.PHONY: serve
 serve:
 	@echo "The serve target was removed, use htmlview instead (see bpo-36329)"
 
@@ -228,22 +251,26 @@ serve:
 # output files)
 
 # for development releases: always build
+.PHONY: autobuild-dev
 autobuild-dev:
 	make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for quick rebuilds (HTML only)
+.PHONY: autobuild-dev-html
 autobuild-dev-html:
 	make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage
+.PHONY: autobuild-stable
 autobuild-stable:
 	@case $(DISTVERSION) in *[ab]*) \
 		echo "Not building; $(DISTVERSION) is not a release version."; \
 		exit 1;; \
 	esac
 	@make autobuild-dev
 
+.PHONY: autobuild-stable-html
 autobuild-stable-html:
 	@case $(DISTVERSION) in *[ab]*) \
 		echo "Not building; $(DISTVERSION) is not a release version."; \

Doc/requirements.txt

@@ -10,6 +10,7 @@ sphinx==4.5.0
 
 blurb
 
+sphinx-autobuild
 sphinxext-opengraph>=0.7.1
 
 # The theme used by the documentation is stored separately, so we need