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.