From 958bd925e64d58a0352868f00169005c987e8966 Mon Sep 17 00:00:00 2001
From: David Pavlovschii <david.pavlovschii@gmail.com>
Date: Tue, 28 Jul 2026 23:48:14 +0300
Subject: [PATCH] docs: fix nitpicky build broken by TYPE_CHECKING-only
 annotations

`tox -e docs` runs `sphinx-build -W` with `nitpicky = True` and has been
failing since 53eeddf with four unresolved reference targets, all in
`src/pluggy/_manager.py`:

    py:class reference target not found: _tracing.TagTracerSub
    py:class reference target not found: _Plugin
    py:class reference target not found: DistFacade

53eeddf moved `DistFacade` into `_compat` and left both `DistFacade` and
`importlib.metadata` as `TYPE_CHECKING`-only imports. Because `_manager`
uses `from __future__ import annotations`, autodoc's `get_type_hints()`
call now raises `NameError` for `list_plugin_distinfo` and
`list_plugin_distributions`, so it falls back to the annotation text as
written in the source. The emitted cross-reference targets changed from
fully qualified to as-written, and `_Plugin` no longer collapses to
`object` -- so the existing fully qualified `nitpick_ignore` entries stop
matching.

Ignore the as-written spellings alongside the qualified ones. These are
all private names that are intentionally not documented, so nothing that
should resolve is being hidden.

The break went unnoticed because CI does not run the `docs` tox env and
ReadTheDocs builds without `-W`.

Refs #417
---
 changelog/417.trivial.rst | 1 +
 docs/conf.py              | 8 ++++++++
 2 files changed, 9 insertions(+)
 create mode 100644 changelog/417.trivial.rst

diff --git a/changelog/417.trivial.rst b/changelog/417.trivial.rst
new file mode 100644
index 00000000..00d15ce8
--- /dev/null
+++ b/changelog/417.trivial.rst
@@ -0,0 +1 @@
+Fix the ``tox -e docs`` build, which failed under ``sphinx-build -W`` because nitpicky mode reported unresolved references to the private names ``_tracing.TagTracerSub``, ``DistFacade`` and ``_Plugin``.
diff --git a/docs/conf.py b/docs/conf.py
index 3f621bd6..fce8fa4c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -63,11 +63,19 @@
 autodoc_member_order = "bysource"
 
 nitpicky = True
+# Some annotations in `pluggy._manager` reference names that only exist under
+# `typing.TYPE_CHECKING` (`DistFacade`, `importlib.metadata`), so autodoc cannot
+# evaluate them and falls back to the annotation as written in the source.
+# That means private names show up both fully qualified and as written.
 nitpick_ignore = {
     # Don't want to expose this yet (see #428).
     ("py:class", "pluggy._tracing.TagTracerSub"),
+    ("py:class", "_tracing.TagTracerSub"),
     # Compat hack, don't want to expose it.
     ("py:class", "pluggy._compat.DistFacade"),
+    ("py:class", "DistFacade"),
+    # Private alias for `object`.
+    ("py:class", "_Plugin"),
     # `types.ModuleType` turns into `module` but then fails to resolve...
     ("py:class", "module"),
     # Just a TypeVar.