Add RtD patching

Author: AA-Turner

build.py

@@ -69,6 +69,7 @@ def create_index_file(html_root: Path, builder: str) -> None:
         confoverrides=config_overrides,
         warningiserror=args.fail_on_warning,
         parallel=args.jobs,
+        tags=["internal_builder"]
     )
     app.builder.copysource = False  # Prevent unneeded source copying - we link direct to GitHub
     app.builder.search = False  # Disable search

pep_sphinx_extensions/__init__.py

@@ -16,6 +16,7 @@
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
+    from sphinx.config import Config
 
 # Monkeypatch sphinx.environment.default_settings as Sphinx doesn't allow custom settings or Readers
 # These settings should go in docutils.conf, but are overridden here for now so as not to affect
@@ -37,12 +38,37 @@ def _depart_maths():
     pass  # No-op callable for the type checker
 
 
-def _update_config_for_builder(app: Sphinx):
+def _check_external_builder(app: Sphinx, conf: Config) -> None:
+    if "internal_builder" not in app.tags:  # internal_builder exists if Sphinx is run by build.py
+        conf.html_context = {"external_builder": True}
+    else:
+        conf.html_context = {"external_builder": False}
+    app.tags.remove("internal_builder")
+
+    if conf.html_context["external_builder"]:
+        app.connect("build-finished", _post_build)  # Post-build tasks
+
+
+def _update_config_for_builder(app: Sphinx) -> None:
+    if app.config.html_context["external_builder"]:
+        app.builder.copysource = False  # Prevent unneeded source copying - we link direct to GitHub
+        app.builder.search = False  # Disable search
+
     if app.builder.name == "dirhtml":
         config.pep_url = f"../{config.pep_stem}"
         app.env.settings["pep_file_url_template"] = "../pep-%04d"
 
 
+def _post_build(app: Sphinx, exception: Exception | None) -> None:
+    from pathlib import Path
+
+    from build import create_index_file
+
+    if exception is not None:
+        return
+    create_index_file(Path(app.outdir), app.builder.name)
+
+
 def setup(app: Sphinx) -> dict[str, bool]:
     """Initialize Sphinx extension."""
 
@@ -51,8 +77,9 @@ def setup(app: Sphinx) -> dict[str, bool]:
     app.add_role("pep", pep_role.PEPRole(), override=True)  # Transform PEP references to links
     app.set_translator("html", pep_html_translator.PEPTranslator)  # Docutils Node Visitor overrides (html builder)
     app.set_translator("dirhtml", pep_html_translator.PEPTranslator)  # Docutils Node Visitor overrides (dirhtml builder)
-    app.connect("env-before-read-docs", create_pep_zero)  # PEP 0 hook
+    app.connect("config-inited", _check_external_builder)  # Check if build is being orchestrated by an external process
     app.connect("builder-inited", _update_config_for_builder)  # Update configuration values for builder used
+    app.connect("env-before-read-docs", create_pep_zero)  # PEP 0 hook
 
     # Mathematics rendering
     inline_maths = HTMLTranslator.visit_math, _depart_maths