From 2238dbcd5a33e9019e59b2fd42e28f7b561f7cd1 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 27 Apr 2025 18:37:31 +0300
Subject: [PATCH 01/10] Remove unused I18NSPHINXOPTS variable

---
 docs/Makefile | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 1e6c06ede80..a8345f1e8c6 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -12,8 +12,6 @@ BUILDDIR      = _build
 PAPEROPT_a4     = --define latex_paper_size=a4
 PAPEROPT_letter = --define latex_paper_size=letter
 ALLSPHINXOPTS   = --doctree-dir $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help
 help:

From 1d4fcb7170b261f9baee6980ea2cdea77f0ad804 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 27 Apr 2025 18:43:33 +0300
Subject: [PATCH 02/10] Add newlines to ALLSPHINXOPTS for readability

---
 docs/Makefile | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/Makefile b/docs/Makefile
index a8345f1e8c6..ba2bb7b096d 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -11,7 +11,10 @@ BUILDDIR      = _build
 # Internal variables.
 PAPEROPT_a4     = --define latex_paper_size=a4
 PAPEROPT_letter = --define latex_paper_size=letter
-ALLSPHINXOPTS   = --doctree-dir $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+ALLSPHINXOPTS   = --doctree-dir $(BUILDDIR)/doctrees \
+                  $(PAPEROPT_$(PAPER)) \
+                  $(SPHINXOPTS) .
 
 .PHONY: help
 help:

From d2fd0f357c489ebd5efba248eea069f201694760 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 27 Apr 2025 18:54:39 +0300
Subject: [PATCH 03/10] Factor out --builder and output build directory

---
 docs/Makefile | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index ba2bb7b096d..c7f0377bc95 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -7,14 +7,17 @@ SPHINXOPTS    =
 SPHINXBUILD   = $(PYTHON) -m sphinx.cmd.build
 PAPER         =
 BUILDDIR      = _build
+BUILDER       = html
 
 # Internal variables.
 PAPEROPT_a4     = --define latex_paper_size=a4
 PAPEROPT_letter = --define latex_paper_size=letter
 
-ALLSPHINXOPTS   = --doctree-dir $(BUILDDIR)/doctrees \
+ALLSPHINXOPTS   = --builder $(BUILDER) \
+                  --doctree-dir $(BUILDDIR)/doctrees \
                   $(PAPEROPT_$(PAPER)) \
-                  $(SPHINXOPTS) .
+                  $(SPHINXOPTS) \
+                  . $(BUILDDIR)/$(BUILDER)
 
 .PHONY: help
 help:
@@ -37,28 +40,31 @@ install-sphinx:
 .PHONY: html
 html:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) --builder html --fail-on-warning --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) --fail-on-warning --keep-going $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: dirhtml
+dirhtml: BUILDER = dirhtml
 dirhtml:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) --builder dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
+singlehtml: BUILDER = singlehtml
 singlehtml:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) --builder singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .PHONY: linkcheck
+linkcheck: BUILDER = linkcheck
 linkcheck:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) --builder linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck -j auto
+	$(SPHINXBUILD) $(ALLSPHINXOPTS) -j auto
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."

From 5af05d384a3e8113df58e471332e5b3725cdc8bc Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 27 Apr 2025 19:04:39 +0300
Subject: [PATCH 04/10] Don't repeat what Sphinx now outputs

---
 docs/Makefile | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index c7f0377bc95..ce19cbbb6f9 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -41,24 +41,18 @@ install-sphinx:
 html:
 	$(MAKE) install-sphinx
 	$(SPHINXBUILD) --fail-on-warning --keep-going $(ALLSPHINXOPTS)
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: dirhtml
 dirhtml: BUILDER = dirhtml
 dirhtml:
 	$(MAKE) install-sphinx
 	$(SPHINXBUILD) $(ALLSPHINXOPTS)
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
 singlehtml: BUILDER = singlehtml
 singlehtml:
 	$(MAKE) install-sphinx
 	$(SPHINXBUILD) $(ALLSPHINXOPTS)
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .PHONY: linkcheck
 linkcheck: BUILDER = linkcheck

From 84d728978f9895929662e53d0dfce3c6e53cf487 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 27 Apr 2025 19:06:38 +0300
Subject: [PATCH 05/10] Use --fail-on-warning --keep-going for all builders

---
 docs/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index ce19cbbb6f9..bd411f4a1c3 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -3,8 +3,8 @@
 
 # You can set these variables from the command line.
 PYTHON        = python3
-SPHINXOPTS    =
 SPHINXBUILD   = $(PYTHON) -m sphinx.cmd.build
+SPHINXOPTS    = --fail-on-warning --keep-going
 PAPER         =
 BUILDDIR      = _build
 BUILDER       = html
@@ -40,7 +40,7 @@ install-sphinx:
 .PHONY: html
 html:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) --fail-on-warning --keep-going $(ALLSPHINXOPTS)
+	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 
 .PHONY: dirhtml
 dirhtml: BUILDER = dirhtml

From 0d2e1dd17d4ddc22f6dc6523be7380eccabbc0b0 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 27 Apr 2025 19:15:05 +0300
Subject: [PATCH 06/10] Use '--jobs auto' for all builders

---
 docs/Makefile | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index bd411f4a1c3..30761b5e017 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -5,9 +5,10 @@
 PYTHON        = python3
 SPHINXBUILD   = $(PYTHON) -m sphinx.cmd.build
 SPHINXOPTS    = --fail-on-warning --keep-going
-PAPER         =
 BUILDDIR      = _build
 BUILDER       = html
+JOBS          = auto
+PAPER         =
 
 # Internal variables.
 PAPEROPT_a4     = --define latex_paper_size=a4
@@ -15,6 +16,7 @@ PAPEROPT_letter = --define latex_paper_size=letter
 
 ALLSPHINXOPTS   = --builder $(BUILDER) \
                   --doctree-dir $(BUILDDIR)/doctrees \
+                  --jobs $(JOBS) \
                   $(PAPEROPT_$(PAPER)) \
                   $(SPHINXOPTS) \
                   . $(BUILDDIR)/$(BUILDER)
@@ -58,7 +60,7 @@ singlehtml:
 linkcheck: BUILDER = linkcheck
 linkcheck:
 	$(MAKE) install-sphinx
-	$(SPHINXBUILD) $(ALLSPHINXOPTS) -j auto
+	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."

From fe1934c91e6a23b392871c01abf0b1e5f73d041e Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 27 Apr 2025 19:19:32 +0300
Subject: [PATCH 07/10] Replace duplicate calls with html target

---
 docs/Makefile | 11 +++--------
 1 file changed, 3 insertions(+), 8 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 30761b5e017..c73471496d7 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -46,21 +46,16 @@ html:
 
 .PHONY: dirhtml
 dirhtml: BUILDER = dirhtml
-dirhtml:
-	$(MAKE) install-sphinx
-	$(SPHINXBUILD) $(ALLSPHINXOPTS)
+dirhtml: html
 
 .PHONY: singlehtml
 singlehtml: BUILDER = singlehtml
-singlehtml:
-	$(MAKE) install-sphinx
-	$(SPHINXBUILD) $(ALLSPHINXOPTS)
+singlehtml: html
 
 .PHONY: linkcheck
 linkcheck: BUILDER = linkcheck
+linkcheck: html
 linkcheck:
-	$(MAKE) install-sphinx
-	$(SPHINXBUILD) $(ALLSPHINXOPTS)
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."

From d4f9221e4ca279bc5fa068d4e34430060489a71e Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Sun, 27 Apr 2025 19:30:18 +0300
Subject: [PATCH 08/10] Remove linkcheck echoes: they won't run if there's an
 error

---
 docs/Makefile | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index c73471496d7..32c1d86001e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -55,10 +55,6 @@ singlehtml: html
 .PHONY: linkcheck
 linkcheck: BUILDER = linkcheck
 linkcheck: html
-linkcheck:
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
 .PHONY: htmlview
 htmlview: html

From 98987be356a331323657082c1897b9149231a7e8 Mon Sep 17 00:00:00 2001
From: Andrew Murray <radarhere@users.noreply.github.com>
Date: Tue, 29 Apr 2025 21:06:56 +1000
Subject: [PATCH 09/10] Remove unused I18NSPHINXOPTS variable

---
 docs/make.bat | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/make.bat b/docs/make.bat
index 4126f786b8d..9d15537fb9e 100644
--- a/docs/make.bat
+++ b/docs/make.bat
@@ -7,10 +7,8 @@ if "%SPHINXBUILD%" == "" (
 )
 set BUILDDIR=_build
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
 )
 
 if "%1" == "" goto help

From 7d5d6d39674042e4cd518fb7bca17f7fb2ca2a5e Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Tue, 29 Apr 2025 15:22:31 +0300
Subject: [PATCH 10/10] Remove redundant --keep-going

Co-authored-by: Andrew Murray <3112309+radarhere@users.noreply.github.com>
---
 docs/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/Makefile b/docs/Makefile
index 32c1d86001e..8c10192940d 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -4,7 +4,7 @@
 # You can set these variables from the command line.
 PYTHON        = python3
 SPHINXBUILD   = $(PYTHON) -m sphinx.cmd.build
-SPHINXOPTS    = --fail-on-warning --keep-going
+SPHINXOPTS    = --fail-on-warning
 BUILDDIR      = _build
 BUILDER       = html
 JOBS          = auto