[3.11] Docs: Add `make htmllive` to rebuild and reload HTML files in your browser...

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

diff --git a/Doc/Makefile b/Doc/Makefile
index ca82353eb454f38a2e435aea671b0d4b548180f0..f01b8a4ff958d9adf0fca3c61ae0332a91bc9aad 100644 (file)
--- a/Doc/Makefile
+++ b/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,38 +71,46 @@ 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) || { \
@@ -111,6 +118,7 @@ linkcheck:
             "or in build/$(BUILDER)/output.txt"; \
        false; }
 
+.PHONY: suspicious
 suspicious: BUILDER = suspicious
 suspicious:
        @$(MAKE) build BUILDER=$(BUILDER) || { \
@@ -123,10 +131,12 @@ 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) || { \
@@ -134,20 +144,30 @@ doctest:
             "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,15 +251,18 @@ 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."; \
@@ -244,6 +270,7 @@ autobuild-stable:
        esac
        @make autobuild-dev
 
+.PHONY: autobuild-stable-html
 autobuild-stable-html:
        @case $(DISTVERSION) in *[ab]*) \
                echo "Not building; $(DISTVERSION) is not a release version."; \

diff --git a/Doc/requirements.txt b/Doc/requirements.txt
index df79ae63840471734d2def6d0fc079d67cb9fa1c..d81fef288caed3227c82e3ababb55f5367556e3e 100644 (file)
--- a/Doc/requirements.txt
+++ b/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