Skip to content

gh-151950: Fix Sphinx reference warnings in Doc/library/importlib.rst - #157610

Merged
brettcannon merged 4 commits into
python:mainfrom
jang-hs:gh-151950-importlib-refs
Sep 17, 2026
Merged

brettcannon merged 4 commits into
python:mainfrom
jang-hs:gh-151950-importlib-refs

Conversation

@jang-hs

@jang-hs jang-hs commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

Eleven "reference target not found" warnings come from Doc/library/importlib.rst (the full list is in the issue), with four separate causes.

Most of them are references written without a module -- Loader.create_module, Loader.exec_module, InspectLoader.is_package and import_module -- used from paragraphs that sit in the importlib.machinery and importlib.util sections, where importlib.abc and importlib are not the current module. The file already spells these out elsewhere, as :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>``` in `module_from_spec()` and as :func:`importlib.import_module``` further down, so this uses the same qualified forms; the rendered text stays as it was.

cache_tag is described inside the sys.implementation entry in Doc/library/sys.rst and has no target of its own. Doc/whatsnew/3.12.rst already links it as ``:attr:`sys.implementation.cache_tag <sys.implementation>```, which is what the two references here now do.

get_resource_reader has not been documented since gh-143513 removed the importlib.abc.ResourceReader section. That commit converted the references left behind in Doc/whatsnew/3.7.rst and Misc/NEWS.d to the suppressed ``:meth:`!...``` form, but missed these two.

The last one, get_tag, is imp.get_tag(), removed in 3.12. The same sentence already points at sys.implementation.cache_tag, which replaced it, so the dead reference is dropped rather than retargeted. That is the only place where the rendered text changes.

I checked with a nit-picky docs build (make -C Doc SPHINXOPTS="--nitpicky --warning-file ..." html) against a clean build of main: the eleven warnings are gone, no new ones appear anywhere in Doc/, and Doc/tools/check-warnings.py --fail-if-regression --fail-if-improved --fail-if-new-news-nit exits 0. Doc/library/importlib.rst therefore comes out of Doc/tools/.nitignore.

Found and fixed with AI assistance. I reproduced the eleven warnings against a clean build of main, traced each one to its cause myself, and checked that the four reference forms used here are the ones already in the tree; the docs build above is my own verification.

Sub-issue of #151940.

…lib.rst`

The Loader, InspectLoader and import_module references were written
without a module from paragraphs in the importlib.machinery and
importlib.util sections, where those names are not in scope; qualify them
the way the rest of the file already does. Link cache_tag to the
sys.implementation entry that documents it, as Doc/whatsnew/3.12.rst does.
get_resource_reader has not been documented since pythongh-143513, so suppress
those two references like that commit did elsewhere, and drop the
reference to imp.get_tag(), removed in 3.12, from a sentence that already
names its replacement.

Doc/library/importlib.rst now builds clean in nit-picky mode and comes out
of Doc/tools/.nitignore.
@read-the-docs-community

read-the-docs-community Bot commented Sep 16, 2026

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #34619929 | 📁 Comparing 22fa4d0 against main (7f52444)

  🔍 Preview build  

5 files changed · ± 5 modified

± Modified

@brettcannon
brettcannon enabled auto-merge (squash) September 17, 2026 18:48
@brettcannon brettcannon self-assigned this Sep 17, 2026
@brettcannon
brettcannon merged commit a9e7895 into python:main Sep 17, 2026
30 checks passed
@hugovk hugovk added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Sep 17, 2026
@miss-islington-app

Copy link
Copy Markdown

Thanks @jang-hs for the PR, and @brettcannon for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

@miss-islington-app

Copy link
Copy Markdown

Thanks @jang-hs for the PR, and @brettcannon for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

@miss-islington-app

Copy link
Copy Markdown

Thanks @jang-hs for the PR, and @brettcannon for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

@bedevere-app

bedevere-app Bot commented Sep 17, 2026

Copy link
Copy Markdown

GH-157701 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Sep 17, 2026
@bedevere-app

bedevere-app Bot commented Sep 17, 2026

Copy link
Copy Markdown

GH-157702 is a backport of this pull request to the 3.15 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Sep 17, 2026
@bedevere-app

bedevere-app Bot commented Sep 17, 2026

Copy link
Copy Markdown

GH-157703 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Sep 17, 2026
hugovk pushed a commit that referenced this pull request Sep 17, 2026
…tlib.rst` (GH-157610) (#157701)

gh-151950: Fix Sphinx reference warnings in `Doc/library/importlib.rst` (GH-157610)
(cherry picked from commit a9e7895)

Co-authored-by: Jade <[email protected]>
hugovk pushed a commit that referenced this pull request Sep 17, 2026
…tlib.rst` (GH-157610) (#157703)

gh-151950: Fix Sphinx reference warnings in `Doc/library/importlib.rst` (GH-157610)
(cherry picked from commit a9e7895)

Co-authored-by: Jade <[email protected]>
hugovk pushed a commit that referenced this pull request Sep 17, 2026
…tlib.rst` (GH-157610) (#157702)

gh-151950: Fix Sphinx reference warnings in `Doc/library/importlib.rst` (GH-157610)
(cherry picked from commit a9e7895)

Co-authored-by: Jade <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir skip news

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants