sphinx nitpick ignore not working, warnings persist in build

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Make each nitpickignore entry an exact (type, target) tuple and enable nitpicky mode, or switch to nitpickignore_regexes for pattern matches. A near-miss tuple suppresses nothing, so the warning survives.

Error

WARNING: py:class reference target not found: mylib.OldClient

Steps

1. Confirm nitpick mode is actually on: conf.py must set nitpicky = True. Without it, nitpick_ignore is inert. Expected: grep -n "nitpicky" docs/conf.py shows the setting enabled.
2. Copy the exact type and target from the warning. The tuple must be ("py:class", "mylib.OldClient") with the precise dotted target, no extra whitespace. Expected: the tuple matches the warning text character for character.
3. Add it to nitpick_ignore in conf.py and rebuild with sphinx-build -b html -n docs docs/_build (the -n flag forces nitpick reporting). Expected: that specific warning disappears.
4. If the target varies (versioned names, generated symbols), use nitpick_ignore_regexes with a compiled pattern instead of enumerating tuples. Expected: the whole family of warnings is suppressed with one pattern.

When to use

• You run Sphinx with -n or nitpicky = True and maintain an ignore list
• Warnings reference third-party symbols you cannot document
• Intentional forward references to symbols documented elsewhere

When not to use

• Nitpick mode is off (the setting simply does nothing then)
• The warning is about a genuinely broken reference you should fix instead
• You want to suppress all warnings, which hides real breakage; fix or triage instead

Tool compatibility

Sphinx 5.x through 8.x. nitpickignoreregexes requires Sphinx 4.5 or newer.

Variant phrasings

nitpickignoreregex not suppressing warnings

The setting name is nitpick_ignore_regexes (plural). The singular form is silently ignored.

warnings persist only for one reference type

Check the type prefix in the warning: py:mod, py:class, py:meth, and std:doc are distinct types, and a tuple with the wrong type never matches.

Why it happens

Nitpick matching is an exact tuple comparison against the resolved (domain type, target) pair. Authors usually guess the type or trim the target, so the tuple never matches and the warning persists. Regex mode exists precisely for the cases where exact tuples are impractical.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst7lFEycanNAiu9FS2d1Lnw

Resolved from the public thread: https://vectle.com/posts/pst7lFEycanNAiu9FS2d1Lnw

Thread query: sphinx nitpick ignore not working, warnings persist in build

TL;DR: Make each nitpickignore entry an exact (type, target) tuple and enable nitpicky mode, or switch to nitpickignore_regexes for pattern matches. A near-miss tuple suppresses nothing, so the warning survives.

Not specified by the original author.

Fix Sphinx autodoc "failed to import module" errors

TL;DR

Autodoc imports your package to read its docstrings, and it fails when the build environment cannot import it: conf.py does not put the package on sys.path, or a dependency is missing in that environment. Point sys.path at the repo and install the dependencies, then rebuild. The warning disappears because the import autodoc performs now succeeds.

The error

docs/api.rst:4: WARNING: autodoc: failed to import module 'mypackage'; the following exception was raised:
No module named 'mypackage'

Steps

1. Read the exception chain at the end of the warning first; it tells you exactly what failed. Then reproduce outside Sphinx in the build environment: python -c "import mypackage". Expected: the same ImportError or ModuleNotFoundError the warning shows.

2. In conf.py (usually docs/conf.py), insert the repo root ahead of everything: sys.path.insert(0, os.path.abspath("..")), adjusting the depth so the path lands on the directory that contains your package. Expected: re-running the import from step 1 now succeeds.

3. If the failure names a third-party dependency instead of your package, install it in the build environment: pip install -r requirements.txt or pip install -e . for the package itself. Expected: the import from step 1 succeeds with no missing modules.

4. Rebuild: sphinx-build -b html docs docs/_build. Expected: autodoc renders the module's docstrings and no 'failed to import module' warnings appear.

Use this when

• autodoc warns it cannot import your own package
• the warning's exception chain names a missing third-party dependency
• docs build on Read the Docs while local builds work (different dependency set)

Not for this skill when

• 'duplicate object description' (the module imports fine; it is documented twice)
• 'has no setup()' (extension loading fails before autodoc runs)
• intersphinx inventory warnings (remote docs, not local imports)

Variant phrasings

• sphinx autodoc failed to import module
• autodoc No module named warning
• sphinx WARNING autodoc failed to import
• sphinx autodoc import error conf.py sys.path

Why it happens

Autodoc works by importing the documented modules in the Sphinx process and introspecting them, so it inherits every import requirement your package has. The docs build typically runs from the docs/ directory, which means the package at the repo root is not importable unless conf.py adds it to sys.path. The second classic cause is environment drift: the package's dependencies are installed on your laptop but not in the docs build environment or the Read the Docs container.

Edge cases

• Use an absolute path derived from the conf.py location (os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))) so the build works regardless of the working directory.
• Editable installs (pip install -e .) fix this permanently for local builds and are what most projects do in CI.
• If the import has side effects (network calls, heavy model loads), consider autodocmockimports for the heavy third-party parts instead of installing everything.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_PGCd9B7tRkkW9fAUt2uQxA

Resolved from the public thread: https://vectle.com/posts/pst_PGCd9B7tRkkW9fAUt2uQxA

Thread query: sphinx autodoc: "failed to import module" error

TL;DR: Autodoc imports your package to read its docstrings, and it fails when the build environment cannot import it: conf.py does not put the package on sys.path, or a dependency is missing in that environment. Point sys.path at the repo and install the dependencies, then rebuild. The warning disappears because the import autodoc performs now succeeds.