docs: enforce Sphinx -W in CI (Sphinx cleanup PR 3)#413
docs: enforce Sphinx -W in CI (Sphinx cleanup PR 3)#413
Conversation
Adds a sphinx-build job to .github/workflows/docs-tests.yml that runs make -C docs html SPHINXOPTS="-W" so warnings become build failures. This locks in the 0-warning state PR #410 achieved and blocks any future warning from sneaking in. The job mirrors the RTD build (.readthedocs.yaml): Python 3.11, pandoc apt package for nbsphinx, and the same docs extras pinned in pyproject.toml [project.optional-dependencies.docs]. Also adds tutorials/21_had_pretest_workflow to the Tutorials: Business Applications toctree at docs/index.rst:84. PR #409 landed this notebook without a toctree entry; -W enforcement caught it on the local smoke test before push. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Overall Assessment✅ Looks good — no unmitigated P0/P1 findings. One non-blocking P2 CI coverage gap is noted. Executive Summary
MethodologyFinding: No methodology defect Code QualityFinding: No code quality defect PerformanceFinding: No performance defect MaintainabilityFinding: No blocking maintainability defect Tech DebtFinding: No new untracked blocker SecurityFinding: No security issue found Documentation/TestsFinding: RTD config-only changes will not trigger the new docs build Validation note: I did not run |
…ters Reviewer caught that the new sphinx-build job mirrors .readthedocs.yaml (Python version, pandoc apt package, post_install docs deps) but the workflow's path filters omitted .readthedocs.yaml. A future PR changing only RTD config (e.g., Python version bump or new apt package) would skip this docs-build guard, allowing drift between CI's mirror and what RTD actually does. Added '.readthedocs.yaml' to both push.paths and pull_request.paths. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
/ai-review |
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment✅ Looks good — no unmitigated P0/P1 findings. The previous P2 path-filter gap is resolved. Executive Summary
MethodologyFinding: No methodology defect Code QualityFinding: Workflow structure is consistent with existing CI gating PerformanceFinding: Expected CI runtime increase from Sphinx build MaintainabilityFinding: RTD mirror is now covered by workflow triggers Tech DebtFinding: No new untracked tech debt SecurityFinding: No security issue found Documentation/TestsFinding: Prior docs-build coverage gap resolved Validation note: I did not run the full Sphinx build because this review workspace is read-only and the real build writes under |
1 participant
Summary
Adds a `sphinx-build` job to `.github/workflows/docs-tests.yml` that runs `make -C docs html SPHINXOPTS="-W"` so any Sphinx warning becomes a build failure. This locks in the 0-warning state PR #410 achieved across the 3-PR Sphinx cleanup wave (PR #405: 86 ERRORs → 0; PR #407: 2,170 → 635 WARNINGs; PR #410: 635 → 0).
The job mirrors the RTD build at `.readthedocs.yaml`: Python 3.11, `pandoc` apt package for nbsphinx, and the same docs extras pinned in `pyproject.toml [project.optional-dependencies.docs]`. Skips the maturin/Rust build (docs/conf.py imports diff_diff via sys.path from checked-out source, matching RTD).
Also adds `tutorials/21_had_pretest_workflow` to the `Tutorials: Business Applications` toctree at `docs/index.rst:84`. PR #409 landed this notebook without a toctree entry; the local smoke test of `-W` caught it before push.
Methodology references
Validation
Security / privacy