docs: module page titles should not start with a link to themselves

[nedbat]

The :mod: role used in the title of module pages turns into a link, but the link is to the same page. That's distracting and unhelpful. This uses the ! prefix to instruct Sphinx to not make a link.

This was done with this thrown-together program:

"""Change every module page in the CPython docs so that the title doesn't link to itself."""frompathlibimportPath# Edge cases:# - modules with a blank line at the top.# - modules that already had the !-prefix to suppress the link.# - had to fix the rule length# - pages that started with a link, but to the main module page.# unittest.mock-examples.rst# - pages with slightly off names:# xml.sax.xmlreader is in xml.sax.reader.rst# xml.etree.ElementTree is in xml.etree.elementtree.rst# xml.parsers.expat is in pyexpat.rst# xml.sax.saxutils is in xml.sax.utils.rst# - pages with two links in the title!# copyreg.rstdeffix_one_file(fpath):
text=fpath.read_text().lstrip()
ifnottext.startswith(":mod:`"):
returniftext.startswith(":mod:`!"):
returnlines=text.splitlines(keepends=True)
modname=lines[0].split("`")[1]
ifmodname!=fpath.stem:
print(f"WUT: {modname=}, {fpath.stem=}")
lines[0] =lines[0].replace(":mod:`", ":mod:`!")
lines[1] =lines[1][0] * (len(lines[0]) -1) +"\n"fpath.write_text("".join(lines))
print(f"Updated {fpath}")
forfnameinPath(".").glob("**/*.rst"):
fix_one_file(fname)

---

📚 Documentation preview 📚: https://cpython-previews--117099.org.readthedocs.build/

[nedbat]

This is only marked Draft because I didn't want to ping 29 other people for review. Can that be stopped?

[AlexWaygood]

This is only marked Draft because I didn't want to ping 29 other people for review. Can that be stopped?

I don't know of a way of avoiding that, unfortunately... It's not possible for me to deselect any of the codeowners from the list of people who are going to be requested for review.

[AlexWaygood]

LGTM, thanks! I agree that these are distracting for readers, and serve no purpose.

While I agree with @CAM-Gerlach's comments on Discord that a Sphinx extension might be a cleaner way of fixing this, I'm personally happy to merge this unless somebody wants to volunteer to actually do that. I think we should prioritise the experience for readers of the docs, and this PR improves the experience of reading the docs.

[nedbat]

Since I don't want to ping 29 code owners, and am a little bit interested in learning about Sphinx internals, let's wait on this to see how the CAM+Ned tag team manages on tweaking Sphinx.

[nedbat]

Everyone: I know this might ping many people. My apologies. The changes were auto-created across all of the module pages.

[serhiy-storchaka]

LGTM.

How we did not notice this earlier?

[miss-islington-app]

Thanks @nedbat for the PR, and @AlexWaygood for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[bedevere-app]

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

[bedevere-app]

GH-118791 is a backport of this pull request to the 3.12 branch.