Skip to content

ci: stabilize docs build workflow #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Gonza10V merged 2 commits into from
Jul 13, 2026
Merged

ci: stabilize docs build workflow #110

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c8b55b6
ci: stabilize docs build workflow
Gonza10V Jul 13, 2026
1d2e2a0
ci: cover docs inputs and resolve API refs
Gonza10V Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 29 additions & 18 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,32 @@
name: Documentation

on:
pull_request:
paths:
- ".github/workflows/docs.yml"
- ".readthedocs.yaml"
- "docs/**"
- "images/**"
- "src/**"
- "tools/update_api_reference.py"
- "pyproject.toml"
Comment on lines +7 to +12

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include all docs build inputs in path filters

With this new paths filter, documentation checks are skipped for PRs that only change files the docs job still consumes, such as setup.py via python -m pip install -e . and images/buildcompiler_logo.png via docs/conf.py's html_logo. Those changes can break the docs install/build but would no longer run this workflow; include those inputs, e.g. setup.py and images/**, in both the pull request and push filters.

Useful? React with 👍 / 👎.

@Gonza10V Gonza10V Jul 13, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@codex good catch, please fix thi issue. Also, some of the problems have not been solved. The workflow should build the documentation on CI and when its pushed into master it updates the online RTD. The remaining issues are:
/home/runner/work/BuildCompiler/BuildCompiler/docs/API_Reference.rst:366: WARNING: more than one target found for cross-reference 'Plasmid': buildcompiler.abstract_translator.Plasmid, buildcompiler.plasmid.Plasmid [ref.python]
/home/runner/work/BuildCompiler/BuildCompiler/docs/API_Reference.rst:366: WARNING: more than one target found for cross-reference 'Plasmid': buildcompiler.abstract_translator.Plasmid, buildcompiler.plasmid.Plasmid [ref.python]

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

Testing

  • ✅ python tools/update_api_reference.py
  • ✅ git diff --check
  • ✅ python - <<'PY' from pathlib import Path for path in ['.github/workflows/docs.yml', 'tools/update_api_reference.py', 'docs/API_Reference.rst']: assert Path(path).read_text(encoding='utf-8').strip() print('changed files are readable') PY
  • ⚠️ python -m pip install -r docs/requirements.txt -q && sphinx-build -b html -W --keep-going docs docs/_build/html — blocked by the environment package index tunnel returning HTTP 403, so Sphinx could not be installed locally.

View task →

- "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: write
contents: read

concurrency:
group: docs-${{ github.ref }}
Expand All @@ -18,35 +38,26 @@ 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: |
python -m pip install --upgrade pip
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
2 changes: 1 addition & 1 deletion .readthedocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ version: 2
build:
os: ubuntu-24.04
tools:
python: "3.10"
python: "3.11"

sphinx:
configuration: docs/conf.py
Expand Down
1 change: 1 addition & 0 deletions docs/API_Reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,7 @@ buildcompiler.abstract_translator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: buildcompiler.abstract_translator
:no-index:
:members:
:undoc-members:
:show-inheritance:
Expand Down
2 changes: 1 addition & 1 deletion docs/requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
sphinx>=7
sphinx>=7,<9
furo>=2024.1.29
10 changes: 8 additions & 2 deletions tools/update_api_reference.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
}

EXCLUDED_MODULES = {"buildcompiler.__init__"}
NO_INDEX_MODULES = {"buildcompiler.abstract_translator"}


def underline(text: str, char: str = "=") -> str:
Expand Down Expand Up @@ -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:
Expand Down
Loading