Docs: use a Sphinx extension to eliminate excessive links

[nedbat]

---

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

[nedbat]

I had a good idea: instead of writing a linter to change .rst files (pinging everyone, expecting reviews, hardcoding what's excessive, etc), now we have a Sphinx extension that does it all on the fly during the build.

[nedbat]

Of course: if we like this, I'll publish linklint for real.

[nedbat]

Some methods aren't unlinking properly, like ZipFile.close, but I think that's because the .rst is wrong: the methods aren't indented under the class. Is that a mistake in the .rst? Sphinx understands that "close" is "ZipFile.close", or is that because the .rst has .. method: ZipFile.close() ?

[nedbat]

I see many classes document their methods that way, so there's more work to do.

[hugovk]

In general I think this is a good idea, no big source change+pings+reviews.

We have been careful not to use third-party extensions that downstream redistributors might not have installed, and this extension would be fine: we can list it in _OPTIONAL_EXTENSIONS instead of extensions and they'll just end up with more links.

---

Comparing some pages that were mentioned during the discussion:

• docs.python.org/dev/library/collections.html#collections.defaultdict.missing
• cpython-previews--145130.org.readthedocs.build/en/145130/library/collections.html#collections.defaultdict.missing

We could possibly omit links for the repeated default_factory in other paragraphs. But I understand if it's a bit risky to automate this for all paragraphs (and some are long) and anyway, it's fine to start with less unlinking and increase later.

---

• https://docs.python.org/dev/c-api/sys.html#c.PyOS_FSPath
• https://cpython-previews--145130.org.readthedocs.build/en/145130/c-api/sys.html#c.PyOS_FSPath

Unlinks the second pair of str and bytes 👍

---

• https://docs.python.org/dev/library/contextlib.html#module-contextlib
• https://cpython-previews--145130.org.readthedocs.build/en/145130/library/contextlib.html#module-contextlib

Unlinks repeats 👍

[nedbat]

I've updated the extension to recognize methods in different class contexts as well. It also prints a message at the end of the build. It now reports:

Linklint unlinked 3612 references.

[nedbat]

Some methods aren't unlinking properly, like ZipFile.close, but I think that's because the .rst is wrong: the methods aren't indented under the class. Is that a mistake in the .rst? Sphinx understands that "close" is "ZipFile.close", or is that because the .rst has .. method: ZipFile.close() ?

ZipFile.close() is now unlinked in its own description.

[nedbat]

Other interesting effects: if a type is mentioned twice in a signature, only the first instance is linked (in this case, BaseException on the logging page):

BTW, it seems silly to link every instance of str, int, tuple, etc in these signatures.

[merwok]

the methods aren't indented under the class.

This style wasn’t always supported, so many classes have one entry for the class itself and another section like «XYZ objects» and methods indexed like ..method XYZ.method

[nedbat]

the methods aren't indented under the class.

This style wasn’t always supported, so many classes have one entry for the class itself and another section like «XYZ objects» and methods indexed like ..method XYZ.method

Thanks. I think linklint properly understands both forms, but I won't be surprised if there are still outliers. The docs are large and diverse!

[m-aciek]

Sharing an idea: if linklint produced an XML report, we could use diff-cover in CI to lint only the new or modified documentation lines in CPython PRs, without forcing changes to the existing documentation.

[nedbat]

Sharing an idea: if linklint produced an XML report, we could use diff-cover in CI to lint only the new or modified documentation lines in CPython PRs, without forcing changes to the existing documentation.

That is an interesting idea! I'm hoping that the Sphinx extension can do what is needed at build time without having to change the source files at all.