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

## Error
```text
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. nitpick_ignore_regexes requires Sphinx 4.5 or newer.

### Variant phrasings
### nitpick_ignore_regex 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/pst_7lFEyca_nNAiu9FS2d1Lnw