Repository navigation
ci: deploy docs with GitHub Pages actions - #85
Conversation
The autodoc job had been failing on every push to main: the shallow checkout has no origin/Documentation ref, and it committed as the retired valbot@valiot.io identity. Docs are now built with Sphinx via uv and deployed as a Pages artifact, so no branch or bot identity is involved. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JDeFLeFBuh3Jg9ULDLwE46
There was a problem hiding this comment.
Overall Assessment
This replaces the broken origin/Documentation bot-commit flow with the official Pages actions. The two-job split, token permissions, and cancel-in-progress: false match GitHub's starter workflow, and the pinned action tags exist. No blocking bugs found.
Findings
No actionable findings.
Notes
uv run --frozen --group devis the right install path.pyproject.tomlalready listssphinxandsphinx-rtd-themein thedevgroup, so the olddocs/requirements.txtis unused by this workflow.docs/conf.pyinserts the repo root onsys.pathand only enablessphinx.ext.napoleon, souv syncis not required beforesphinx-build.-W --keep-goingfails the build on warnings and still prints the rest. That is stricter than the previoussphinx-actionstep; a warning that used to ship will now fail the workflow.ubuntu-latestmatches the other workflows here. The PR notes the X64/ARM64 runners are private-repo only.- Considered flagging the workflow-level
pages: write/id-token: writepermissions. They apply to the build job as well as deploy. That is the documented starter-workflow layout, so it is not a defect.
🤖 PR Reviewer · Grok 4.7 (xAI)
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
Review effort: Lite
Findings: 4
Open (4)
All third-party actions are pinned by tag rather than by full commit SHA. Tags can be retargeted,… · Newuv run --frozenrequires a checked-in lockfile (typicallyuv.lock) that matches the current… · New All third-party actions are pinned by tag rather than by full commit SHA. Tags can be retargeted,… · New All third-party actions are pinned by tag rather than by full commit SHA. Tags can be retargeted,… · New
What changed in this PR
Updates the docs CI workflow to build Sphinx docs with uv and deploy them via GitHub Pages Actions instead of committing generated docs to a Documentation branch.
Changes:
- Replace branch-based docs publishing with Pages artifact +
deploy-pages. - Switch Sphinx build to
uv runand fail on warnings (-W). - Add
workflow_dispatch, Pages permissions, and deployment concurrency controls.
| File | Description |
|---|---|
| .github/workflows/autodoc.yml | Reworks docs workflow to build with uv and deploy to GitHub Pages using official Pages actions |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| - uses: actions/checkout@v7.0.1 | ||
|
|
||
| - name: Setting up Python 3.13 & env vars | ||
| uses: actions/setup-python@v6 | ||
| - name: Install uv | ||
| uses: astral-sh/setup-uv@v10.2.0 |
| run: uv python install 3.13 | ||
|
|
||
| - name: Build documentation | ||
| run: uv run --frozen --group dev sphinx-build -W --keep-going -b html docs docs/_build/html |
| - uses: actions/configure-pages@v6.0.0 | ||
|
|
||
| - uses: actions/upload-pages-artifact@v5.0.0 |
| url: ${{ steps.deployment.outputs.page_url }} | ||
| steps: | ||
| - id: deployment | ||
| uses: actions/deploy-pages@v5.0.1 |

The docs workflow has failed on every push to
mainsince at least June: the shallow checkout has noorigin/Documentationref, sogit checkout origin/Documentationerrors out. It also committed asvalbot@valiot.io, which no longer exists.uv(dev group already hassphinx+sphinx-rtd-theme), with-Wso doc warnings fail the build.configure-pages/upload-pages-artifact/deploy-pages— no bot commit, noDocumentationbranch.workflow_dispatchfor manual rebuilds.ubuntu-latest: the repo is public and our X64/ARM64 runners serve private repos only.Requires Pages source = "GitHub Actions" (Settings → Pages). The
Documentationbranch can be deleted once the first deploy lands.🤖 Generated with Claude Code
https://claude.ai/code/session_01JDeFLeFBuh3Jg9ULDLwE46