Infra: Faster incremental builds, up to 5.4x (#4848)

Author: hugovk

.github/workflows/render.yml

@@ -42,7 +42,7 @@ jobs:
           python -m pip install --upgrade pip
 
       - name: Render PEPs
-        run: make dirhtml JOBS=$(nproc)
+        run: make dirhtml search JOBS=$(nproc)
 
         # remove the .doctrees folder when building for deployment as it takes two thirds of disk space
       - name: Clean up files

.readthedocs.yaml

@@ -13,7 +13,7 @@ build:
     - asdf plugin add uv
     - asdf install uv latest
     - asdf global uv latest
-    - make dirhtml JOBS=$(nproc) BUILDDIR=_readthedocs/html
+    - make dirhtml search JOBS=$(nproc) BUILDDIR=_readthedocs/html
 
 sphinx:
   builder: dirhtml

Makefile

@@ -22,7 +22,6 @@ ALLSPHINXOPTS = --builder $(BUILDER) \
 .PHONY: html
 html: venv
 	$(SPHINXBUILD) $(ALLSPHINXOPTS)
-	$(VENVDIR)/bin/python3 -m pagefind --site $(BUILDDIR) --verbose
 
 ## htmlview       to open the index page built by the html target in your browser
 .PHONY: htmlview
@@ -43,6 +42,11 @@ dirhtml: BUILDER = dirhtml
 dirhtml: html
 	mv $(BUILDDIR)/404/index.html $(BUILDDIR)/404.html
 
+## search         to rebuild the search index
+.PHONY: search
+search: venv
+	$(VENVDIR)/bin/python3 -m pagefind --site $(BUILDDIR) --verbose
+
 ## linkcheck      to check validity of links within PEP sources
 .PHONY: linkcheck
 linkcheck: BUILDER = linkcheck

pep_sphinx_extensions/pep_zero_generator/subindices.py

@@ -16,11 +16,17 @@
 
 def update_sphinx(filename: str, text: str, docnames: list[str], env: BuildEnvironment) -> Path:
     file_path = Path(env.srcdir, f"{filename}.rst")
-    file_path.write_text(text, encoding="utf-8")
-
-    # Add to files for builder
-    docnames.append(filename)
-    # Add to files for writer
+    # Only write and schedule for rebuild if content actually changed
+    try:
+        current = file_path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        current = None
+    if current != text:
+        file_path.write_text(text, encoding="utf-8")
+        if filename not in docnames:
+            docnames.append(filename)
+
+    # Always ensure Sphinx knows about the file
     env.found_docs.add(filename)
 
     return file_path

peps/conf.py

@@ -43,6 +43,9 @@
     "api/*.rst",
     # Documentation
     "docs/*.rst",
+    # Generated index files
+    "numerical.rst",
+    "topic/*.rst",
 ]
 # And to ignore when looking for source files.
 exclude_patterns = [