From c8b55b62e11f47851b8baed76bfe19a60dd458d6 Mon Sep 17 00:00:00 2001
From: Gonzalo Vidal <35148159+Gonza10V@users.noreply.github.com>
Date: Mon, 13 Jul 2026 10:41:21 -0600
Subject: [PATCH 1/2] ci: stabilize docs build workflow

---
 .github/workflows/docs.yml | 42 ++++++++++++++++++++++----------------
 .readthedocs.yaml          |  2 +-
 docs/requirements.txt      |  2 +-
 3 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ae9cfdf..da66c97 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,12 +1,27 @@
 name: Documentation
 
 on:
+  pull_request:
+    paths:
+      - ".github/workflows/docs.yml"
+      - ".readthedocs.yaml"
+      - "docs/**"
+      - "src/**"
+      - "tools/update_api_reference.py"
+      - "pyproject.toml"
   push:
     branches:
       - main
+    paths:
+      - ".github/workflows/docs.yml"
+      - ".readthedocs.yaml"
+      - "docs/**"
+      - "src/**"
+      - "tools/update_api_reference.py"
+      - "pyproject.toml"
 
 permissions:
-  contents: write
+  contents: read
 
 concurrency:
   group: docs-${{ github.ref }}
@@ -18,14 +33,15 @@ jobs:
     steps:
       - name: Check out repository
         uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            docs/requirements.txt
 
       - name: Install documentation dependencies
         run: |
@@ -33,20 +49,10 @@ jobs:
           python -m pip install -e .
           python -m pip install -r docs/requirements.txt
 
-      - name: Update API reference record
-        run: python tools/update_api_reference.py
+      - name: Verify API reference is current
+        run: |
+          python tools/update_api_reference.py
+          git diff --exit-code -- docs/API_Reference.rst
 
       - name: Build Read the Docs site
         run: sphinx-build -b html -W --keep-going docs docs/_build/html
-
-      - name: Commit API reference updates
-        run: |
-          if git diff --quiet -- docs/API_Reference.rst; then
-            echo "API reference is already current."
-            exit 0
-          fi
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add docs/API_Reference.rst
-          git commit -m "docs: update API reference"
-          git push
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 5e15702..7393263 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.10"
+    python: "3.11"
 
 sphinx:
   configuration: docs/conf.py
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 9103101..1f3942c 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,2 @@
-sphinx>=7
+sphinx>=7,<9
 furo>=2024.1.29

From 1d2e2a06b446f44540a1f18c9562cbbc18651206 Mon Sep 17 00:00:00 2001
From: Gonzalo Vidal <35148159+Gonza10V@users.noreply.github.com>
Date: Mon, 13 Jul 2026 11:55:54 -0600
Subject: [PATCH 2/2] ci: cover docs inputs and resolve API refs

---
 .github/workflows/docs.yml    |  5 +++++
 docs/API_Reference.rst        |  1 +
 tools/update_api_reference.py | 10 ++++++++--
 3 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index da66c97..2777604 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -6,19 +6,24 @@ on:
       - ".github/workflows/docs.yml"
       - ".readthedocs.yaml"
       - "docs/**"
+      - "images/**"
       - "src/**"
       - "tools/update_api_reference.py"
       - "pyproject.toml"
+      - "setup.py"
   push:
     branches:
       - main
+      - master
     paths:
       - ".github/workflows/docs.yml"
       - ".readthedocs.yaml"
       - "docs/**"
+      - "images/**"
       - "src/**"
       - "tools/update_api_reference.py"
       - "pyproject.toml"
+      - "setup.py"
 
 permissions:
   contents: read
diff --git a/docs/API_Reference.rst b/docs/API_Reference.rst
index eb21fda..122da37 100644
--- a/docs/API_Reference.rst
+++ b/docs/API_Reference.rst
@@ -358,6 +358,7 @@ buildcompiler.abstract_translator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: buildcompiler.abstract_translator
+   :no-index:
    :members:
    :undoc-members:
    :show-inheritance:
diff --git a/tools/update_api_reference.py b/tools/update_api_reference.py
index 5cd8053..52a5b8d 100644
--- a/tools/update_api_reference.py
+++ b/tools/update_api_reference.py
@@ -32,6 +32,7 @@
 }
 
 EXCLUDED_MODULES = {"buildcompiler.__init__"}
+NO_INDEX_MODULES = {"buildcompiler.abstract_translator"}
 
 
 def underline(text: str, char: str = "=") -> str:
@@ -61,16 +62,21 @@ def modules_for_section(modules: list[str], package: str) -> list[str]:
 
 
 def render_module(name: str) -> list[str]:
-    return [
+    lines = [
         name,
         underline(name, "~"),
         "",
         f".. automodule:: {name}",
+    ]
+    if name in NO_INDEX_MODULES:
+        lines.append("   :no-index:")
+    lines.extend([
         "   :members:",
         "   :undoc-members:",
         "   :show-inheritance:",
         "",
-    ]
+    ])
+    return lines
 
 
 def render_api_reference() -> str: