Avoid over-linking #1293 (#1294)

* Avoid over-linking

* Update documentation/markup.rst

Co-authored-by: Éric <[email protected]>

* two updates from comments

* update per ezio-melotti's comment

#1294 (comment)

* fix a sphinx lint failure

* Update documentation/markup.rst

Co-authored-by: Hugo van Kemenade <[email protected]>

---------

Co-authored-by: Éric <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>

Author: 3 people

documentation/markup.rst

@@ -753,6 +753,10 @@ versatile:
   In HTML output, the link's ``title`` attribute (that is e.g. shown as a
   tool-tip on mouse-hover) will always be the full target name.
 
+* Combining ``~`` and ``!`` (for example, ``:meth:`~!Queue.Queue.get```) is not
+  supported.  You can obtain the same result by using ``!`` and the last
+  component of the target (for example, ``:meth:`!get```).
+
 The following roles refer to objects in modules and are possibly hyperlinked if
 a matching identifier is found:
 

documentation/style-guide.rst

@@ -127,11 +127,39 @@ explanation.
   provide context, make connections between topics, and discuss alternative
   opinions. There is no section dedicated to explanations but these can be
   found throughout Python's documentation, for example the
-  :ref:`python:unicode-howto`
+  :ref:`python:unicode-howto`.
 
 Please consult the `Diátaxis <https://diataxis.fr/>`_ guide for more
 detail.
 
+Links
+=====
+
+Links are a powerful tool for helping people navigate documentation and find
+more information, but links can be over-used.  Links should be used only if
+they help the reader.
+
+Generally, a link should be provided for the first use of a term in a unit,
+such as a section or paragraph. This is not a hard and fast rule.  Sometimes
+the second mention is more appropriate for a link.  Some units are long enough
+to have a few repeated links.  Use judgement to decide when a link will help
+the reader.
+
+Do not use a link when the link would point to the current unit.  It's natural
+to use the name of a function in the documentation for the function, but a link
+on that function name that simply reloads the section the user is already
+reading is useless and distracting.
+
+Do not use links in section headers.  They distract from the title of the
+section.  The term will be mentioned in the paragraph text and can be linked
+from there.
+
+Sphinx provides ways to automatically add links to references, and a way to
+suppress the link.  Using roles like ``:func:`map``` will link to the
+documentation for ``map``.  You can suppress the link while keeping the
+semantic presentation of the function name by adding an exclamation point
+prefix: ``:func:`!map```.  See :ref:`roles` for more details.
+
 Affirmative tone
 ================