Docs: module pages should not link to themselves

[nedbat]

The style guide says that sections should not link to themselves, since it is a pointless distraction. This updates module pages to remove links to themselves.

Done automatically with https://github.com/nedbat/odds/blob/master/rstwork/unlink-mod.py

Updated: relevant style guide section: https://devguide.python.org/documentation/style-guide/#links

---

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

[nedbat]

(sorry for the pings)

[picnixz]

Ok for ssl/hashlib

[serhiy-storchaka]

This is quite a churn.

I don't think that it is so bad for module links, because the module documentation is usually much larger than a section, so the link usually leads beyond the screen. It is also possible to have documentation for several modules in the same file -- in that case links are useful, because they allow to find the start of the module documentation. When you read the documentation, its organization (several modules in one file or each module in a separate file) should not bother you -- links should work the same way. Even if you have a single module per file, clicking a link can be more convenient than scrolling to the beginning.

[nedbat]

I don't think that it is so bad for module links, because the module documentation is usually much larger than a section, so the link usually leads beyond the screen. It is also possible to have documentation for several modules in the same file -- in that case links are useful, because they allow to find the start of the module documentation. When you read the documentation, its organization (several modules in one file or each module in a separate file) should not bother you -- links should work the same way. Even if you have a single module per file, clicking a link can be

My problem with links to the same page is that they fool you into thinking they will take you to a new place about the module, but they don't, you are back where you started. If I want to read the beginning of the page, I know what to do: I scroll to the top of the page. Links should help the reader. Linking to the same page isn't something readers need.

[serhiy-storchaka]

I think that links at the beginning of the module documentation, in its preamble, should be avoided, but links in the documentation of its components should be kept. You may not even be aware that the link refers to the same page. You could read the documentation for foo(), then jumped to the documentation for bar() (in the baz module), which contains a link to the module, -- and at that moment you man not figure that it is the same module, because you did not start reading it from start.

[nedbat]

You may not even be aware that the link refers to the same page. You could read the documentation for foo(), then jumped to the documentation for bar() (in the baz module), which contains a link to the module

I think a self-link is even worse if the reader is unware that it's a self-link. That just adds to the disappointing surprise of being on the same page.

These changes only remove links when they are to the module named in the first line of the file. You've mentioned two-module pages a few times: are there examples like that in this PR? I'd like to understand it better.