python
docs: module page titles should not start with a link to themselves
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/
This is only marked Draft because I didn't want to ping 29 other people for review. Can that be stopped?
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.
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.