Skip to content

ci: deploy docs with GitHub Pages actions - #85

Merged
acrogenesis merged 1 commit into
mainfrom
acrogenesis/fix-autodoc-pages
Oct 4, 2026
Merged

acrogenesis merged 1 commit into
mainfrom
acrogenesis/fix-autodoc-pages

Conversation

@acrogenesis

Copy link
Copy Markdown
Member

The docs workflow has failed on every push to main since at least June: the shallow checkout has no origin/Documentation ref, so git checkout origin/Documentation errors out. It also committed as valbot@valiot.io, which no longer exists.

  • Build Sphinx with uv (dev group already has sphinx + sphinx-rtd-theme), with -W so doc warnings fail the build.
  • Deploy with configure-pages / upload-pages-artifact / deploy-pages — no bot commit, no Documentation branch.
  • All actions pinned to their latest releases; added workflow_dispatch for manual rebuilds.
  • Stays on ubuntu-latest: the repo is public and our X64/ARM64 runners serve private repos only.

Requires Pages source = "GitHub Actions" (Settings → Pages). The Documentation branch can be deleted once the first deploy lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JDeFLeFBuh3Jg9ULDLwE46

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
Copilot AI balanced review requested due to automatic review settings October 4, 2026 18:28

@palantir-valiot palantir-valiot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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 dev is the right install path. pyproject.toml already lists sphinx and sphinx-rtd-theme in the dev group, so the old docs/requirements.txt is unused by this workflow.
  • docs/conf.py inserts the repo root on sys.path and only enables sphinx.ext.napoleon, so uv sync is not required before sphinx-build.
  • -W --keep-going fails the build on warnings and still prints the rest. That is stricter than the previous sphinx-action step; a warning that used to ship will now fail the workflow.
  • ubuntu-latest matches the other workflows here. The PR notes the X64/ARM64 runners are private-repo only.
  • Considered flagging the workflow-level pages: write / id-token: write permissions. 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)

@acrogenesis
acrogenesis merged commit d64036d into main Oct 4, 2026
6 of 7 checks passed
@acrogenesis
acrogenesis deleted the acrogenesis/fix-autodoc-pages branch October 4, 2026 18:33

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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 Medium severity

Open (4)
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 run and 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.

Comment on lines +23 to +26
- 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
Comment on lines +36 to +38
- 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants