docs: fix nitpicky build for TYPE_CHECKING-only annotations - #715
Open
davidpavlovschi wants to merge 1 commit into
Open
docs: fix nitpicky build for TYPE_CHECKING-only annotations#715davidpavlovschi wants to merge 1 commit into
davidpavlovschi wants to merge 1 commit into
Conversation
`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 pytest-dev#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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
tox -e docscurrently fails onmainbecause Sphinx runs in nitpicky mode with warnings treated as errors and cannot resolve four private annotation targets frompluggy._manager.The annotations now fall back to their source spellings when
typing.get_type_hints()encounters names imported only underTYPE_CHECKING. The existingnitpick_ignoreentries cover the qualified spellings, but not the emitted_tracing.TagTracerSub,DistFacade, and_Plugintargets.This adds those three precise targets to
nitpick_ignore. It does not broaden the ignore pattern or change runtime code.Refs #417.
Test plan
uv run pytest— 141 passeduv run pre-commit run -a— all 11 hooks passeduv run --with tox tox -e docs— build succeeded (failed before this change)AI assistance
I used Claude Code with Claude Opus 5 to investigate the regression, prepare the patch, and run an adversarial review. The commit includes the corresponding co-author and session attribution.