support read the docs

build.py

@@ -81,6 +81,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.build()
 

pep_sphinx_extensions/__init__.py

@@ -5,6 +5,7 @@
 from typing import TYPE_CHECKING
 
 from docutils.writers.html5_polyglot import HTMLTranslator
+from jinja2.environment import Template
 from sphinx import environment
 
 from pep_sphinx_extensions.pep_processor.html import pep_html_builder
@@ -22,17 +23,32 @@ def _depart_maths():
     pass  # No-op callable for the type checker
 
 
-def _update_config_for_builder(app: Sphinx):
+def _update_config_for_builder(app: Sphinx) -> None:
     app.env.document_ids = {}  # For PEPReferenceRoleTitleText
     if app.builder.name == "dirhtml":
         app.env.settings["pep_url"] = "../pep-{:0>4}"
 
+    # internal_builder exists if Sphinx is run by build.py
+    if "internal_builder" not in app.tags:
+        app.connect("build-finished", _post_build)  # Post-build tasks
+
+
+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."""
 
     environment.default_settings["pep_url"] = "pep-{:0>4}.html"
     environment.default_settings["halt_level"] = 2  # Fail on Docutils warning
+    Template.render._patched = True  # don't modify rendered HTML
 
     # Register plugin logic
     app.add_builder(pep_html_builder.FileBuilder, override=True)

readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+python:
+  install:
+    - requirements: requirements.txt
+
+sphinx:
+  builder: dirhtml
+
+search:
+  ignore: ['*']