go

lukegalbraithrussell · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
commit 6353313d95844ce07c9f00665cf6ee614d16c75c
@@ -58,6 +58,27 @@ jobs:
       - name: Type check all modules
         run: mypy --config-file pyproject.toml
 
+  docs-reference:
+    name: Reference docs drift
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python ${{ env.LATEST_SUPPORTED_PY }}
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ env.LATEST_SUPPORTED_PY }}
+      # Regenerating also runs the MDX/acorn hazard gate inside the generator,
+      # so a stale tree or an unfenced code example both fail here.
+      - name: Regenerate the API reference
+        run: ./scripts/generate_api_docs.sh
+      - name: Fail if the committed reference is out of date
+        run: git diff --exit-code -- docs/english/reference
+
   unittest:
     name: Unit tests
     runs-on: ubuntu-22.04

diff --git a/requirements/documentation.txt b/requirements/documentation.txt
@@ -0,0 +1,8 @@
+# pip install -r requirements/documentation.txt
+
+# griffe
+# Note: doc-gen only; the generator runs on the latest supported Python (see
+# scripts/generate_api_docs.sh), so no python_version markers are needed.
+# Note: pinned so the committed reference tree under docs/english/reference stays
+# reproducible -- an unpinned griffe can silently shift the generated Markdown.
+griffe==2.2.0
@@ -10,7 +10,7 @@ cd "${script_dir}/.."
 pip install -U pip
 pip install -U -r requirements/adapter_dev.txt
 pip install -U -r requirements/async_dev.txt
-pip install -U griffe
+pip install -U -r requirements/documentation.txt
 pip install .
 rm -rf docs/english/reference