ci: Add CI for doc build warnings#8
Conversation
There was a problem hiding this comment.
Pull request overview
Adds stricter documentation build enforcement to catch Sphinx warnings/errors earlier, plus local tooling to run the same check via pre-commit.
Changes:
- Add a strict Sphinx build target (
stricthtml) and use it in GitHub Pages docs workflow. - Add a local pre-commit hook for strict docs builds and include
pre-commitas a dependency. - Tweak docs content/formatting to avoid Sphinx warnings and update README instructions accordingly.
Reviewed changes
Copilot reviewed 5 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| requirements.txt | Adds pre-commit to installed tooling. |
| README.md | Updates local build instructions and documents the strict-build check workflow. |
| docs/overview/exploiting_function_geometry.rst | Fixes formatting likely to produce Sphinx warnings. |
| docs/Makefile | Adds stricthtml target that fails on warnings. |
| .pre-commit-config.yaml | Introduces local hook to enforce strict docs builds. |
| .gitignore | Ignores Python __pycache__/ artifacts. |
| .github/workflows/docs.yml | Switches CI docs build step to strict mode (warnings as errors). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 7 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 7 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| permissions: | ||
| contents: read | ||
| pages: write | ||
| id-token: write | ||
|
|
There was a problem hiding this comment.
The build job runs actions/configure-pages@v5 and actions/upload-pages-artifact@v3 on non-PR events, but the workflow-level permissions only grants contents: read. configure-pages typically requires pages: write (and often id-token: write), so pushes to main/master may fail with insufficient token permissions. Consider adding the required permissions to the build job (or restoring them at the workflow level) while keeping the steps gated for pull requests.
There was a problem hiding this comment.
We will find out if this is a problem...
TheoRudkiewicz
left a comment
TheoRudkiewicz
left a comment
There was a problem hiding this comment.
I approve the idea ! (For the code I trust copilot more than myself)
This PR adds a CI and corresponding pre-commit hook to assert that docs are built without errors or warnings. This should help prevent accidental regressions / broken pages in the docs.