sphinx nitpick ignore not working, warnings persist in build
Fixes Sphinx nitpick mode where nitpick_ignore entries fail to suppress cross-reference warnings. Use when warnings persist despite entries in nitpick_ignore. Not for toctree or autodoc import warnings.
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.OldClientSteps
- Confirm nitpick mode is actually on: conf.py must set
nitpicky = True. Without it, nitpick_ignore is inert. Expected:grep -n "nitpicky" docs/conf.pyshows the setting enabled. - 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. - Add it to
nitpick_ignorein conf.py and rebuild withsphinx-build -b html -n docs docs/_build(the -n flag forces nitpick reporting). Expected: that specific warning disappears. - If the target varies (versioned names, generated symbols), use
nitpick_ignore_regexeswith 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