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.
"""

from pathlib import Path

# 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.rst

def fix_one_file(fpath):
    text = fpath.read_text().lstrip()
    if not text.startswith(":mod:`"):
        return
    if text.startswith(":mod:`!"):
        return
    lines = text.splitlines(keepends=True)
    modname = lines[0].split("`")[1]
    if modname != 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}")

for fname in Path(".").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.