Docs: avoid repetitions of class references in functions.rst

[m-aciek]

With Linklint we link only first reference in a paragraph. In effect references intended to link aren't links.

Simplify descriptions to avoid repetitions and this issue. In dict, frozendict, frozenset and set reference docs.

Before:

After:

Changelog:

• first iteration was mechanically changing which references are links
• second iteration does editorial change to avoid repetitions

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32991391 | 📁 Comparing de4af58 against main (7a468a1)

  🔍 Preview build  

7 files changed · ± 7 modified

± Modified

• c-api/complex.html
• extending/first-extension-module.html
• library/functions.html
• library/shlex.html
• library/stdtypes.html
• whatsnew/3.16.html
• whatsnew/changelog.html

[hugovk]

Thanks!

@nedbat Although I wonder if linklint could prefer linking the instances in a "See x [and y]" sentence, or would that be unreliable?

[nedbat]

As I read these paragraphs, I wonder what value these sentences actually add:

• "The [dict] object is the dictionary class."
• "[frozenset] is a built-in class."

About linklint: it's an interesting idea to preserve links in "See ..." sentences. I wonder if it is reliable enough, and if there are other sentence structures to consider. Also, what about translations?

[hugovk]

As I read these paragraphs, I wonder what value these sentences actually add:

Good point: "See x and y for documentation on x and y" is rather pointless! Let's delete them and just have the previous mentions link as usual.

Something like this?

    Create a new dictionary.  The :class:`dict` object is the dictionary class.
-   See :class:`dict` and :ref:`typesmapping` for documentation about this class.
+   See also :ref:`typesmapping` for documentation about this class.

[m-aciek]

Thank you for the review! I've simplified all paragraphs.

Also, what about translations?

We would need to maintain also translations' sentence structures to keep this behaviour for localised docs.

In Polish the one-to-one translation would be Zobacz [ref], but often (and in cases here) we don't use direct translation, but phrase it differently for better reading, it would be needed to use znajduje się {…} [ref]. All in all in my opinion there's potential for it to become impractical to maintain, as costly and fragile.