From 119a37326e810233056004edfff101ac94a758ca Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 17 Aug 2024 18:13:00 +0100
Subject: [PATCH 1/8] Use `$(MAKE)` over `make`

---
 Doc/Makefile | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/Doc/Makefile b/Doc/Makefile
index 9ddf97fd775dec..56f9bcc8fe2a11 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -188,7 +188,7 @@ dist:
 	mkdir -p dist
 
 	# archive the HTML
-	make html
+	$(MAKE) html
 	cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
 	bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar
@@ -197,7 +197,7 @@ dist:
 	rm dist/python-$(DISTVERSION)-docs-html.tar
 
 	# archive the text build
-	make text
+	$(MAKE) text
 	cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
 	bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar
@@ -207,29 +207,29 @@ dist:
 
 	# archive the A4 latex
 	rm -rf build/latex
-	make latex PAPER=a4
+	$(MAKE) latex PAPER=a4
 	-sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
-	(cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
 
 	# archive the letter latex
 	rm -rf build/latex
-	make latex PAPER=letter
+	$(MAKE) latex PAPER=letter
 	-sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
-	(cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
 
 	# copy the epub build
 	rm -rf build/epub
-	make epub
+	$(MAKE) epub
 	cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
 
 	# archive the texinfo build
 	rm -rf build/texinfo
-	make texinfo
-	make info --directory=build/texinfo
+	$(MAKE) texinfo
+	$(MAKE) info --directory=build/texinfo
 	cp -pPR build/texinfo dist/python-$(DISTVERSION)-docs-texinfo
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-texinfo.tar python-$(DISTVERSION)-docs-texinfo
 	bzip2 -9 -k dist/python-$(DISTVERSION)-docs-texinfo.tar
@@ -271,12 +271,12 @@ serve:
 # for development releases: always build
 .PHONY: autobuild-dev
 autobuild-dev:
-	make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(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'
+	$(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
@@ -286,7 +286,7 @@ autobuild-stable:
 		echo "Not building; $(DISTVERSION) is not a release version."; \
 		exit 1;; \
 	esac
-	@make autobuild-dev
+	@$(MAKE) autobuild-dev
 
 .PHONY: autobuild-stable-html
 autobuild-stable-html:
@@ -294,4 +294,4 @@ autobuild-stable-html:
 		echo "Not building; $(DISTVERSION) is not a release version."; \
 		exit 1;; \
 	esac
-	@make autobuild-dev-html
+	@$(MAKE) autobuild-dev-html

From 10e46883f2b42fe09dbff675019469d53b24a869 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 17 Aug 2024 18:13:33 +0100
Subject: [PATCH 2/8] Add start/finish logging to the ``dist`` target

---
 Doc/Makefile | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Doc/Makefile b/Doc/Makefile
index 56f9bcc8fe2a11..8743101db300cd 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -188,6 +188,7 @@ dist:
 	mkdir -p dist
 
 	# archive the HTML
+	@echo "Building HTML..."
 	$(MAKE) html
 	cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
@@ -195,8 +196,10 @@ dist:
 	(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html)
 	rm -r dist/python-$(DISTVERSION)-docs-html
 	rm dist/python-$(DISTVERSION)-docs-html.tar
+	@echo "Build finished and archived!"
 
 	# archive the text build
+	@echo "Building text..."
 	$(MAKE) text
 	cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
 	tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
@@ -204,29 +207,37 @@ dist:
 	(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text)
 	rm -r dist/python-$(DISTVERSION)-docs-text
 	rm dist/python-$(DISTVERSION)-docs-text.tar
+	@echo "Build finished and archived!"
 
 	# archive the A4 latex
+	@echo "Building LaTeX (A4 paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=a4
 	-sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
 	(cd build/latex; $(MAKE) clean && $(MAKE) all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
+	@echo "Build finished and archived!"
 
 	# archive the letter latex
+	@echo "Building LaTeX (US paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=letter
 	-sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
 	(cd build/latex; $(MAKE) clean && $(MAKE) all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
+	@echo "Build finished and archived!"
 
 	# copy the epub build
+	@echo "Building EPUB..."
 	rm -rf build/epub
 	$(MAKE) epub
 	cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
+	@echo "Build finished and archived!"
 
 	# archive the texinfo build
+	@echo "Building Texinfo..."
 	rm -rf build/texinfo
 	$(MAKE) texinfo
 	$(MAKE) info --directory=build/texinfo
@@ -236,6 +247,7 @@ dist:
 	(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-texinfo.zip python-$(DISTVERSION)-docs-texinfo)
 	rm -r dist/python-$(DISTVERSION)-docs-texinfo
 	rm dist/python-$(DISTVERSION)-docs-texinfo.tar
+	@echo "Build finished and archived!"
 
 .PHONY: _ensure-package
 _ensure-package: venv

From 9dd54909260bfa094b3a9b6048216b6b3c8c2ebb Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 17 Aug 2024 18:15:43 +0100
Subject: [PATCH 3/8] Remove makeindex manipulation

The Makefile template switched to `latexmk` and stopped using `makeindex`
on 2016-10-23, first released in Sphinx 1.6
---
 Doc/Makefile | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Doc/Makefile b/Doc/Makefile
index 8743101db300cd..5afa43b5973439 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -213,7 +213,6 @@ dist:
 	@echo "Building LaTeX (A4 paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=a4
-	-sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
 	(cd build/latex; $(MAKE) clean && $(MAKE) all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
@@ -223,7 +222,6 @@ dist:
 	@echo "Building LaTeX (US paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=letter
-	-sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
 	(cd build/latex; $(MAKE) clean && $(MAKE) all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2

From bb3a201f74d7cc9ca30e738787cac4f995359d12 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 17 Aug 2024 18:17:14 +0100
Subject: [PATCH 4/8] Run make in parallel

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

diff --git a/Doc/Makefile b/Doc/Makefile
index 5afa43b5973439..dc090d3856b763 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -213,7 +213,7 @@ dist:
 	@echo "Building LaTeX (A4 paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=a4
-	(cd build/latex; $(MAKE) clean && $(MAKE) all-pdf && $(MAKE) FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
 	@echo "Build finished and archived!"
@@ -222,7 +222,7 @@ dist:
 	@echo "Building LaTeX (US paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=letter
-	(cd build/latex; $(MAKE) clean && $(MAKE) all-pdf && $(MAKE) FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
 	@echo "Build finished and archived!"

From 029e72b3a954b50f7c0d9629e072fd4aaccd5364 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 17 Aug 2024 18:17:33 +0100
Subject: [PATCH 5/8] Reduce latexmk verbosity

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

diff --git a/Doc/Makefile b/Doc/Makefile
index dc090d3856b763..a6063016dc62dc 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -213,7 +213,7 @@ dist:
 	@echo "Building LaTeX (A4 paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=a4
-	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync all-pdf && $(MAKE) FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
 	@echo "Build finished and archived!"
@@ -222,7 +222,7 @@ dist:
 	@echo "Building LaTeX (US paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=letter
-	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync all-pdf && $(MAKE) FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
 	@echo "Build finished and archived!"

From 701a893339d66c7bbf50f8703402abfc400833e5 Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 17 Aug 2024 18:17:53 +0100
Subject: [PATCH 6/8] Don't run the full ``latexmk`` process twice

---
 Doc/Makefile | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Doc/Makefile b/Doc/Makefile
index a6063016dc62dc..25b7ec2134a867 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -213,6 +213,10 @@ dist:
 	@echo "Building LaTeX (A4 paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=a4
+	# remove zip & bz2 dependency on all-pdf,
+	# as otherwise the full latexmk process is run twice.
+	# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
+	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
 	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
@@ -222,6 +226,10 @@ dist:
 	@echo "Building LaTeX (US paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=letter
+	# remove zip & bz2 dependency on all-pdf,
+	# as otherwise the full latexmk process is run twice.
+	# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
+	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
 	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2

From 3539828fc29ddc9ff23d516bd6bf4229713ffc8b Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 17 Aug 2024 19:14:55 +0100
Subject: [PATCH 7/8] Review notes

---
 Doc/Makefile | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/Doc/Makefile b/Doc/Makefile
index 25b7ec2134a867..afd2734dc8ec9e 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -226,9 +226,6 @@ dist:
 	@echo "Building LaTeX (US paper)..."
 	rm -rf build/latex
 	$(MAKE) latex PAPER=letter
-	# remove zip & bz2 dependency on all-pdf,
-	# as otherwise the full latexmk process is run twice.
-	# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
 	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
 	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
@@ -265,11 +262,11 @@ _ensure-package: venv
 
 .PHONY: _ensure-pre-commit
 _ensure-pre-commit:
-	make _ensure-package PACKAGE=pre-commit
+	$(MAKE) _ensure-package PACKAGE=pre-commit
 
 .PHONY: _ensure-sphinx-autobuild
 _ensure-sphinx-autobuild:
-	make _ensure-package PACKAGE=sphinx-autobuild
+	$(MAKE) _ensure-package PACKAGE=sphinx-autobuild
 
 .PHONY: check
 check: _ensure-pre-commit

From bb27b560fbbf6f8ca5349cc067e811e34d1d983c Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Sat, 17 Aug 2024 21:40:10 +0100
Subject: [PATCH 8/8] Use nproc + 1

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

diff --git a/Doc/Makefile b/Doc/Makefile
index afd2734dc8ec9e..8020884447983c 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -217,7 +217,7 @@ dist:
 	# as otherwise the full latexmk process is run twice.
 	# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
 	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
-	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$((`nproc`+1)) --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
 	@echo "Build finished and archived!"
@@ -227,7 +227,7 @@ dist:
 	rm -rf build/latex
 	$(MAKE) latex PAPER=letter
 	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
-	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=12 --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$((`nproc`+1)) --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
 	@echo "Build finished and archived!"