Skip to content

Commit de8d418

Browse files
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 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JB8YrcUSkrAojQfiNacSZJ
1 parent 21bb5d1 commit de8d418

2 files changed

Lines changed: 9 additions & 0 deletions

File tree

changelog/417.trivial.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
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``.

docs/conf.py

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,11 +63,19 @@
6363
autodoc_member_order = "bysource"
6464

6565
nitpicky = True
66+
# Some annotations in `pluggy._manager` reference names that only exist under
67+
# `typing.TYPE_CHECKING` (`DistFacade`, `importlib.metadata`), so autodoc cannot
68+
# evaluate them and falls back to the annotation as written in the source.
69+
# That means private names show up both fully qualified and as written.
6670
nitpick_ignore = {
6771
# Don't want to expose this yet (see #428).
6872
("py:class", "pluggy._tracing.TagTracerSub"),
73+
("py:class", "_tracing.TagTracerSub"),
6974
# Compat hack, don't want to expose it.
7075
("py:class", "pluggy._compat.DistFacade"),
76+
("py:class", "DistFacade"),
77+
# Private alias for `object`.
78+
("py:class", "_Plugin"),
7179
# `types.ModuleType` turns into `module` but then fails to resolve...
7280
("py:class", "module"),
7381
# Just a TypeVar.

0 commit comments

Comments
 (0)