From cedcb49acec877fd220c4fd642f5016c42f1bd71 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date: Thu, 15 Aug 2024 14:07:44 +0100
Subject: [PATCH] Modernise the `make` templates (#1370)

---
 Makefile | 134 ++++++----------------------------------
 make.bat | 182 +++++++++----------------------------------------------
 make.ps1 |  99 ++++++++++++++++++++++++++++++
 3 files changed, 144 insertions(+), 271 deletions(-)
 create mode 100644 make.ps1

diff --git a/Makefile b/Makefile
index 1f8e73e289..5503d3e15c 100644
--- a/Makefile
+++ b/Makefile
@@ -10,50 +10,31 @@ SPHINXOPTS   = --fail-on-warning --keep-going
 BUILDDIR     = _build
 BUILDER      = html
 JOBS         = auto
-PAPER        =
 SPHINXLINT   = $(VENVDIR)/bin/sphinx-lint
 REQUIREMENTS = requirements.txt
 
 # Internal variables.
-PAPEROPT_a4     = --define latex_paper_size=a4
-PAPEROPT_letter = --define latex_paper_size=letter
-ALLSPHINXOPTS   = --builder $(BUILDER) \
-                  --doctree-dir $(BUILDDIR)/doctrees \
-                  --jobs $(JOBS) \
-                  $(PAPEROPT_$(PAPER)) \
-                  $(SPHINXOPTS) \
-                  . $(BUILDDIR)/$(BUILDER)
+_ALL_SPHINX_OPTS = --jobs $(JOBS) $(SPHINXOPTS)
+_RELEASE_CYCLE   = include/branches.csv \
+                   include/end-of-life.csv \
+                   include/release-cycle.svg
 
 .PHONY: help
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  venv       to create a venv with necessary tools"
 	@echo "  html       to make standalone HTML files"
+	@echo "  linkcheck  to check all external links for integrity"
 	@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 "  clean      to remove the venv and build files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  check      to run a check for frequent markup errors"
 	@echo "  lint       to lint all the files"
-	@echo "  versions   to update release cycle after changing release-cycle.json"
 
 .PHONY: clean
 clean: clean-venv
 	-rm -rf $(BUILDDIR)/*
+	-rm -rf $(_RELEASE_CYCLE)
 
 .PHONY: clean-venv
 clean-venv:
@@ -83,89 +64,6 @@ ensure-venv:
 		echo "The venv has been created in the $(VENVDIR) directory"; \
 	fi
 
-.PHONY: html
-html: ensure-venv versions
-	$(SPHINXBUILD) $(ALLSPHINXOPTS)
-
-.PHONY: dirhtml
-dirhtml: BUILDER = dirhtml
-dirhtml: html
-
-.PHONY: singlehtml
-singlehtml: BUILDER = singlehtml
-singlehtml: html
-
-.PHONY: pickle
-pickle: BUILDER = pickle
-pickle: html
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-.PHONY: json
-json: BUILDER = json
-json: html
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-.PHONY: htmlhelp
-htmlhelp: BUILDER = htmlhelp
-htmlhelp: html
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/$(BUILDER)."
-
-.PHONY: qthelp
-qthelp: BUILDER = qthelp
-qthelp: html
-
-.PHONY: devhelp
-devhelp: BUILDER = devhelp
-devhelp: html
-
-.PHONY: epub
-epub: BUILDER = epub
-epub: html
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/$(BUILDER)."
-
-.PHONY: latex
-latex: BUILDER = latex
-latex: html
-
-.PHONY: latexpdf
-latexpdf: BUILDER = latex
-latexpdf: html
-	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/$(BUILDER)."
-
-.PHONY: text
-text: BUILDER = text
-text: html
-
-.PHONY: man
-man: BUILDER = man
-man: html
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/$(BUILDER)."
-
-.PHONY: changes
-changes: BUILDER = changes
-changes: html
-
-.PHONY: linkcheck
-linkcheck: BUILDER = linkcheck
-linkcheck: html
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/$(BUILDER)/output.txt."
-
-.PHONY: doctest
-doctest: BUILDER = doctest
-doctest: html
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/$(BUILDER)/output.txt."
-
 .PHONY: htmlview
 htmlview: html
 	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('_build/html/index.html'))"
@@ -198,15 +96,17 @@ _ensure-pre-commit:
 lint: _ensure-pre-commit
 	$(VENVDIR)/bin/python3 -m pre_commit run --all-files
 
-include/branches.csv: include/release-cycle.json
-	$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py
-
-include/end-of-life.csv: include/release-cycle.json
-	$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py
+# Defined so that "include/release-cycle.json"
+# doesn't fall through to the catch-all target.
+include/release-cycle.json:
+	@exit
 
-include/release-cycle.svg: include/release-cycle.json
+$(_RELEASE_CYCLE): include/release-cycle.json
 	$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py
-
-.PHONY: versions
-versions: venv include/branches.csv include/end-of-life.csv include/release-cycle.svg
 	@echo Release cycle data generated.
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.
+.PHONY: Makefile
+%: Makefile ensure-venv $(_RELEASE_CYCLE)
+	$(SPHINXBUILD) -M $@ "." "$(BUILDDIR)" $(_ALL_SPHINX_OPTS)
diff --git a/make.bat b/make.bat
index 3358cb693c..c2ba9b7149 100644
--- a/make.bat
+++ b/make.bat
@@ -10,23 +10,9 @@ if "%PYTHON%" == "" (
 	set PYTHON=py -3
 )
 
-if not defined SPHINXLINT (
-    %PYTHON% -c "import sphinxlint" > nul 2> nul
-    if errorlevel 1 (
-        echo Installing sphinx-lint with %PYTHON%
-        rem Should have been installed with Sphinx earlier
-        %PYTHON% -m pip install "sphinx-lint<1"
-        if errorlevel 1 exit /B
-    )
-    set SPHINXLINT=%PYTHON% -m sphinxlint
-)
-
 set BUILDDIR=_build
-set SPHINXOPTS=-W --keep-going --nitpicky
-set ALLSPHINXOPTS=--doctree-dir %BUILDDIR%/doctrees %SPHINXOPTS% .
-if NOT "%PAPER%" == "" (
-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-)
+set SPHINXOPTS=--fail-on-warning --keep-going
+set _ALL_SPHINX_OPTS=%SPHINXOPTS%
 
 if "%1" == "check" goto check
 
@@ -60,6 +46,14 @@ if "%1" == "clean" (
 	goto end
 )
 
+if "%1" == "versions" (
+	%PYTHON% _tools/generate_release_cycle.py
+	if errorlevel 1 exit /b 1
+	echo.
+	echo Release cycle data generated.
+	goto end
+)
+
 rem Targets other than "clean", "check", "help", or "" need the
 rem Sphinx build command, which the user may define via SPHINXBUILD.
 
@@ -75,157 +69,37 @@ if not defined SPHINXBUILD (
 	set SPHINXBUILD=venv\Scripts\sphinx-build
 )
 
-if "%1" == "html" (
-	%SPHINXBUILD% --builder html %ALLSPHINXOPTS% %BUILDDIR%/html
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
-
 if "%1" == "htmlview" (
-    cmd /C %this% html
-
-    if EXIST "%BUILDDIR%\html\index.html" (
-        echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
-        start "" "%BUILDDIR%\html\index.html"
-    )
-
-    goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% --builder dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-	goto end
-)
-
-if "%1" == "singlehtml" (
-	%SPHINXBUILD% --builder singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% --builder pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% --builder json %ALLSPHINXOPTS% %BUILDDIR%/json
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% --builder htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% --builder qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PythonDevelopersGuide.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PythonDevelopersGuide.ghc
-	goto end
-)
-
-if "%1" == "devhelp" (
-	%SPHINXBUILD% --builder devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished.
-	goto end
-)
-
-if "%1" == "epub" (
-	%SPHINXBUILD% --builder epub %ALLSPHINXOPTS% %BUILDDIR%/epub
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The epub file is in %BUILDDIR%/epub.
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% --builder latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-	goto end
-)
+	cmd /C %this% html
 
-if "%1" == "text" (
-	%SPHINXBUILD% --builder text %ALLSPHINXOPTS% %BUILDDIR%/text
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The text files are in %BUILDDIR%/text.
-	goto end
-)
-
-if "%1" == "man" (
-	%SPHINXBUILD% --builder man %ALLSPHINXOPTS% %BUILDDIR%/man
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Build finished. The manual pages are in %BUILDDIR%/man.
-	goto end
-)
+	if EXIST "%BUILDDIR%\html\index.html" (
+		echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
+		start "" "%BUILDDIR%\html\index.html"
+	)
 
-if "%1" == "changes" (
-	%SPHINXBUILD% --builder changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.The overview file is in %BUILDDIR%/changes.
 	goto end
 )
 
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% --builder linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-	goto end
-)
+%SPHINXBUILD% -M %1 "." %BUILDDIR% %_ALL_SPHINX_OPTS%
+goto end
 
-if "%1" == "doctest" (
-	%SPHINXBUILD% --builder doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
+:check
+if not defined SPHINXLINT (
+	rem If it is not defined, we build in a virtual environment
+	if not exist venv (
+		echo.    Setting up the virtual environment
+		%PYTHON% -m venv venv
+		echo.    Installing requirements
+		venv\Scripts\python -m pip install -r requirements.txt
+	)
+	set PYTHON=venv\Scripts\python
+	set SPHINXLINT=%PYTHON% -m sphinxlint
 )
 
-:check
 rem Ignore the tools and venv dirs and check that the default role is not used.
 cmd /S /C "%SPHINXLINT% -i tools -i venv --enable default-role"
 goto end
 
-if "%1" == "versions" (
-	%PYTHON% _tools/generate_release_cycle.py
-	if errorlevel 1 exit /b 1
-	echo.
-	echo Release cycle data generated.
-	goto end
-)
-
 :end
 popd
 endlocal
diff --git a/make.ps1 b/make.ps1
new file mode 100644
index 0000000000..71a8f56f4c
--- /dev/null
+++ b/make.ps1
@@ -0,0 +1,99 @@
+# Command file for Sphinx documentation
+
+param (
+    [string]$target = "help"
+)
+
+Set-StrictMode -Version 3.0
+$ErrorActionPreference = "Stop"
+
+$BUILDDIR = "_build"
+$SPHINXOPTS = "--fail-on-warning --keep-going"
+$_ALL_SPHINX_OPTS = $SPHINXOPTS
+
+$_PYTHON = $Env:PYTHON ?? "py -3"
+$_SPHINX_BUILD = $Env:SPHINXBUILD ?? ".\venv\Scripts\sphinx-build"
+$_SPHINX_LINT = $Env:SPHINXLINT ?? ".\venv\Scripts\sphinx-lint"
+$_VENV_DIR = "venv"
+
+function New-VirtualEnviromnent
+{
+    Write-Host "Creating venv in $_VENV_DIR"
+    if (Get-Command "uv" -ErrorAction SilentlyContinue) {
+        & uv venv $_VENV_DIR
+        $Env:VIRTUAL_ENV = $_VENV_DIR
+        & uv pip install -r requirements.txt
+        Remove-Item Env:VIRTUAL_ENV
+    } else {
+        & $_PYTHON -m venv venv
+        Write-Host "Installing requirements"
+        & venv\Scripts\python -m pip install -r requirements.txt
+        $Script:_PYTHON = "venv\Scripts\python"
+    }
+}
+
+function Invoke-SphinxBuild
+{
+    param (
+        [string]$BuilderName,
+        [string]$BuildDir,
+        [string]$Options
+    )
+    if (-Not (Test-Path -Path $_VENV_DIR)) { New-VirtualEnviromnent }
+    & $_SPHINX_BUILD -M $BuilderName "." $BuildDir $Options.Split(" ")
+}
+
+function Invoke-Check {
+    if (-Not (Test-Path -Path $_VENV_DIR)) { New-VirtualEnviromnent }
+    & $_SPHINX_LINT -i tools -i venv --enable default-role
+}
+
+if ($target -Eq "help") {
+    Write-Host "Please use `make <target>` where <target> is one of"
+    Write-Host "  venv       to create a venv with necessary tools"
+    Write-Host "  html       to make standalone HTML files"
+    Write-Host "  linkcheck  to check all external links for integrity"
+    Write-Host "  htmlview   to open the index page built by the html target in your browser"
+    Write-Host "  clean      to remove the venv and build files"
+    Write-Host "  check      to check for stylistic and formal issues using sphinx-lint"
+    Write-Host "  versions   to update release cycle after changing release-cycle.json"
+    Exit
+}
+
+if ($target -Eq "clean") {
+    $ToClean = @(
+        $BUILDDIR,
+        $_VENV_DIR,
+        "include/branches.csv", "include/end-of-life.csv", "include/release-cycle.svg"
+    )
+    foreach ($item in $ToClean) {
+        if (Test-Path -Path $item) {
+            Remove-Item -Path $item -Force -Recurse
+        }
+    }
+    Exit $LASTEXITCODE
+}
+
+if ($target -Eq "check") {
+    Invoke-Check
+    Exit $LASTEXITCODE
+}
+
+if ($target -Eq "versions") {
+    & $_PYTHON _tools/generate_release_cycle.py
+    if ($LASTEXITCODE -Ne 0) { exit 1 }
+    Write-Host "Release cycle data generated."
+    Exit $LASTEXITCODE
+}
+
+if ($target -Eq "htmlview") {
+    Invoke-SphinxBuild "html" "$BUILDDIR" "$_ALL_SPHINX_OPTS"
+    if (Test-Path -Path "$BUILDDIR\html\index.html") {
+        Write-Host "Opening $BUILDDIR\html\index.html in the default web browser..."
+        Start-Process "$BUILDDIR\html\index.html"
+    }
+    Exit $LASTEXITCODE
+}
+
+Invoke-SphinxBuild "$target" "$BUILDDIR" "$_ALL_SPHINX_OPTS"
+Exit $LASTEXITCODE