Skip to content

Enable intersphinx so stdlib references resolve - #624

Open
faresrafat3 wants to merge 1 commit into
python-poetry:masterfrom
faresrafat3:tomlkit-192-intersphinx
Open

faresrafat3 wants to merge 1 commit into
python-poetry:masterfrom
faresrafat3:tomlkit-192-intersphinx

Conversation

@faresrafat3

Copy link
Copy Markdown

Fixes #192 (partially).

Building the docs with sphinx-build -n reports many warnings of the form:

<unknown>:1: WARNING: py:class reference target not found: collections.abc.Mapping [ref.class]
<unknown>:1: WARNING: py:class reference target not found: datetime.datetime [ref.class]
<unknown>:1: WARNING: py:class reference target not found: collections.abc.Sequence [ref.class]

The cause is that docs/conf.py only enables sphinx.ext.autodoc; with no
intersphinx mapping, references to the standard library cannot be resolved.

Change

Adds sphinx.ext.intersphinx and the Python inventory:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.intersphinx",
]

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}

Verification

Measured with the same command on the unmodified and modified tree:

before: 55 warnings
after:  31 warnings

All collections.abc.* and datetime.* warnings are gone. The remaining 31
are project-internal targets (tomlkit.items.ItemT,
tomlkit.container.Container, E, Encoder, and a docutils formatting
warning in the register_encoder docstring) which need separate fixes and are
not addressed here.

Building the docs with `sphinx-build -n` reports many
"py:class reference target not found" warnings for annotations such as
collections.abc.Mapping, datetime.datetime and collections.abc.Sequence,
because no intersphinx mapping is configured (see python-poetry#192).

Add the sphinx.ext.intersphinx extension with the Python inventory.

Warnings under -n drop from 55 to 31. The remainder are project-internal
references (tomlkit.items.ItemT, tomlkit.container.Container, E, Encoder)
that are not part of this change.

Fixes python-poetry#192 (partially).
Copilot AI balanced review requested due to automatic review settings October 1, 2026 12:38

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0.10.2: sphinx warnings reference target not found

2 participants