docs agent failed: sphinx nitpick warnings leaked into the published build
Fixes docs-agent pipelines that publish Sphinx builds with nitpick warnings still present. Use when a published build contains warnings the agent should have caught. Not for one-off local build warnings.
TL;DR
Make the agent's build step fail on warnings (sphinx-build -W) and fix the underlying references instead of publishing anyway. A publishing pipeline that tolerates warnings will always leak them.
Error
WARNING: py:class reference target not found: mylib.OldClient
(published to production with the warning unresolved)Steps
- Change the agent's build command to include
-W(warnings as errors) and-n(nitpick mode):sphinx-build -b html -W -n docs docs/_build. Expected: the build now fails instead of publishing warnings. - Run it and collect the full warning list; fix each reference or add exact nitpick_ignore tuples for intentional ones. Expected: zero warnings with -n enabled.
- Add a CI gate that blocks the publish step when the docs build exits nonzero. Expected: broken docs can no longer reach production.
- Re-run the agent pipeline end to end. Expected: the published build is warning-free.
When to use
- Published docs contain warnings the build had reported
- A docs agent runs sphinx-build without -W
- Nitpick warnings appear in production output
When not to use
- Warnings appear only in local builds (fix them, but no pipeline change needed)
- The warnings are new Sphinx-version noise (triage before gating)
- You intentionally publish with known warnings (document the exceptions instead)
Tool compatibility
Sphinx 5.x through 8.x. The -W and -n flags are stable across all of them.
Variant phrasings
agent publishes despite -W because it retries without the flag
Pin the build command in the pipeline definition; do not let the agent improvise flags.
warnings leak only for autodoc references
The agent documents code it did not import correctly. Fix the import path first, then gate.
Why it happens
Agents optimize for "build succeeded", and Sphinx succeeds with warnings by default. Without -W the pipeline cannot distinguish a clean build from a warning-filled one, so warnings ship.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_QbXdBYqf-K8oy7dIMSlpmA