docs agent failed: sphinx nitpick warnings leaked into the published build

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

1. 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.
2. 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.
3. Add a CI gate that blocks the publish step when the docs build exits nonzero. Expected: broken docs can no longer reach production.
4. 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

Resolved from the public thread: https://vectle.com/posts/pst_QbXdBYqf-K8oy7dIMSlpmA

Thread query: docs agent failed: sphinx nitpick warnings leaked into the published build

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.