docs: enforce Sphinx -W in CI (Sphinx cleanup PR 3)#413
Conversation
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 |
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>
…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>
igerber
force-pushed
the
docs/sphinx-warnings-as-errors
branch
from
35ad65b to
86cc916
Compare
|
/ai-review |
|
🔁 AI review rerun (requested by @igerber) Head SHA: Overall Assessment✅ Looks good — no unmitigated P0/P1/P2 findings in the loaded diff. The prior path-filter gap remains addressed: Executive Summary
MethodologyFinding: No methodology-impacting code changedSeverity: P3 informational Code QualityFinding: Sphinx job is structurally clear and scopedSeverity: P3 informational Finding: Previous path-filter gap is addressedSeverity: P3 informational PerformanceFinding: CI runtime increases by designSeverity: P3 informational MaintainabilityFinding: Manual docs dependency list must remain synchronizedSeverity: P3 informational Tech DebtFinding: No new untracked tech debt visibleSeverity: P3 informational SecurityFinding: No security issue found in loaded diffSeverity: P3 informational Documentation/TestsFinding: Docs navigation now includes T21 tutorialSeverity: P3 informational Finding: Sphinx warning enforcement is implemented as CI validationSeverity: P3 informational |
CI's new Sphinx HTML build (-W) failed with "Pygments lexer name
'ipython3' is not known [misc.highlighting_failure]" warnings on every
.ipynb in docs/tutorials/. nbsphinx renders notebook code cells with the
ipython3 lexer; that lexer ships with the IPython package and is not
included in our docs extras. My local venv had IPython transitively
(common dev dep), masking the gap. RTD has been emitting these warnings
silently since it builds without -W.
Added "ipython>=8.0" to all three sync'd surfaces:
- pyproject.toml [project.optional-dependencies.docs]
- .readthedocs.yaml post_install pip install
- .github/workflows/docs-tests.yml sphinx-build job
Verified locally with python3 -c "from pygments.lexers import
get_lexer_by_name; print(get_lexer_by_name('ipython3'))" — returns
<pygments.lexers.IPython3> when IPython is installed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Companion to commit 51022b5 which added ipython to the workflow only. Per the workflow comment "Keep in sync with pyproject.toml [project.optional-dependencies.docs] and .readthedocs.yaml post_install", add the same dep to the other two surfaces so RTD builds (which run without -W) also stop emitting silent highlighting_failure warnings on notebook code cells. 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/P2 findings in the loaded diff. Executive Summary
MethodologyFinding: No methodology-impacting code changedSeverity: P3 informational Finding: T21 tutorial toctree addition aligns with registrySeverity: P3 informational Code QualityFinding: Sphinx warning enforcement is clearly scopedSeverity: P3 informational Finding: Dependency synchronization improved across docs surfacesSeverity: P3 informational Finding: Previous path-filter concern remains resolvedSeverity: P3 informational PerformanceFinding: Docs CI runtime increases by designSeverity: P3 informational MaintainabilityFinding: Manual dependency list still requires synchronizationSeverity: P3 informational Tech DebtFinding: No new untracked tech debt visibleSeverity: P3 informational SecurityFinding: No security issue found in loaded diffSeverity: P3 informational Documentation/TestsFinding: CI job is the appropriate validation surface for Sphinx warning enforcementSeverity: P3 informational Finding: RTD/CI docs dependency parity for
|
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