ci: stabilize docs build workflow

[Gonza10V]

Motivation

• The docs deployment job was mutating and pushing docs/API_Reference.rst during the build which is brittle for protected branches and read-only CI tokens.
• The workflow required repository write permissions and could silently succeed by committing generated artifacts instead of failing when checked-in artifacts are stale.
• Read-the-Docs and GitHub Actions used different Python runtimes and an unbounded Sphinx requirement which made builds sensitive to environment drift and future Sphinx major releases.

Description

• Update .github/workflows/docs.yml to add a pull_request trigger for docs/source/config changes and to run the docs build on Python 3.11 with pip caching by setting cache: pip and cache-dependency-path to pyproject.toml and docs/requirements.txt.
• Change permissions in .github/workflows/docs.yml from contents: write to contents: read and remove the CI step that committed/pushed docs/API_Reference.rst, replacing it with a deterministic freshness check python tools/update_api_reference.py && git diff --exit-code -- docs/API_Reference.rst.
• Align Read-the-Docs runtime by updating .readthedocs.yaml to use Python 3.11.
• Pin Sphinx in docs/requirements.txt to sphinx>=7,<9 to avoid unplanned breakage from future major Sphinx releases.

Testing

• Ran python tools/update_api_reference.py && git diff --exit-code -- docs/API_Reference.rst and the freshness check succeeded.
• Ran git diff --check to validate there are no whitespace or diff issues and it succeeded.
• Ran a small Python smoke-check that reads .github/workflows/docs.yml and .readthedocs.yaml to ensure the files are non-empty and readable and it succeeded.
• Attempted local pip install and sphinx-build to reproduce the full build but the package index is unreachable in this environment (HTTP 403 Tunnel connection failed) which caused install failures for build tools and Sphinx so the full Sphinx build could not be completed here.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8b55b62e1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

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]

@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]

Summary

• Expanded the docs workflow path filters to include images/** and setup.py for both PR and push events, so docs CI runs when all relevant docs build inputs change. .github/workflows/docs.ymlL4-L13 .github/workflows/docs.ymlL18-L26
• Added master to the docs workflow push branches alongside main, so pushes to master also run the docs build needed for the RTD update flow. .github/workflows/docs.ymlL14-L17
• Updated the API reference generator to mark buildcompiler.abstract_translator as a no-index module, preventing duplicate Sphinx Python targets for Plasmid while still documenting the module. tools/update_api_reference.pyL34-L35 tools/update_api_reference.pyL64-L79
• Regenerated docs/API_Reference.rst so the legacy abstract_translator automodule uses :no-index:. docs/API_Reference.rstL357-L364
• Committed changes on the current branch with commit 3072519 and created the PR via the make_pr tool.

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 →