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.

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.