Improve cross-reference documentation

Closes #12940.

doc/usage/domains/python.rst

@@ -716,15 +716,39 @@ a matching identifier is found:
 
    .. versionadded:: 0.4
 
-The name enclosed in this markup can include a module name and/or a class name.
-For example, ``:py:func:`filter``` could refer to a function named ``filter``
-in the current module, or the built-in function of that name.  In contrast,
-``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the
-``foo`` module.
+Target specification
+....................
 
-Normally, names in these roles are searched first without any further
+The target can be specified as a fully qualified name, e.g.
+``:py:meth:`mymodule.MyClass.my_method```, or any shortended version
+(``:py:meth:`MyClass.my_method```, ``:py:meth:`my_method```). See
+`python-target-resolution`_ for details on the resolution of shortend names.
+
+:ref:`Cross-referencing modifiers <xref-syntax>` can be applied. In short:
+
+* You may supply an explicit title and reference target: ``:mod:`mathematical
+  functions <math>``` will refer to the ``math`` module, but the link text
+  will be "mathematical functions".
+
+* If you prefix the content with an exclamation mark ``!``, no reference/hyperlink
+  will be created.
+
+* If you prefix the content with ``~``, the link text will only be the last
+  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
+  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
+
+.. _python-target-resolution:
+
+Target resolution
+.................
+
+A given link target name is resolved to an object using the following strategy:
+
+Names in these roles are searched first without any further
 qualification, then with the current module name prepended, then with the
-current module and class name (if any) prepended.  If you prefix the name with
+current module and class name (if any) prepended.
+
+If you prefix the name with
 a dot, this order is reversed.  For example, in the documentation of Python's
 :mod:`codecs` module, ``:py:func:`open``` always refers to the built-in
 function, while ``:py:func:`.open``` refers to :func:`codecs.open`.

doc/usage/referencing.rst

@@ -4,25 +4,32 @@
 Cross-referencing syntax
 ========================
 
-Cross-references are generated by many semantic interpreted text roles.
-Basically, you only need to write ``:role:`target```, and a link will be
-created to the item named *target* of the type indicated by *role*.  The link's
-text will be the same as *target*.
+Sphinx supports various cross-referencing roles to create links to other elements in
+the documentation. Writing ``:role:`target``` creates a link to the item named
+*target* of the type indicated by *role*. The link's text depends the role but is
+often the same as or similar to *target*.
 
-There are some additional facilities, however, that make cross-referencing
-roles more versatile:
+The behavior can be modified in the following ways:
 
-* You may supply an explicit title and reference target,
-  like in reStructuredText direct hyperlinks:
-  ``:role:`title <target>``` will refer to *target*,
-  but the link text will be *title*.
+* **Custom link text:** You can specify the link text explicitly using the same
+  notation as in reStructuredText :ref:`rst-external-links`:
+  ``:role:`link text <target>``` will refer to *target*, but the link text will be
+  *link text*.
 
-* If you prefix the content with ``!``, no reference/hyperlink will be created.
+* **Surpressed link:** Prefixing with an exclamation mark ``!``, prevents the
+  creation of a link but otherwise keeps the visual output of the role. Example:
+  ``:role:`!target```.
 
-* If you prefix the content with ``~``, the link text will only be the last
-  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
-  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.  This
-  does not work with all cross-reference roles, but is domain specific.
+  This is helpful for cases, in which the link target does not exist; e.g.
+  changelog entries that target removed functionality, or third-party libraries
+  without intersphinx. Surpressing the link prevents warnings in :confval:`nitpicky`
+  mode.
+
+* **Modified domain reference:**
+  When :ref:`referencing domain objects <ref-objects>`, a tilde ``~`` prefix shortens
+  the link text the last component of the target.
+  For example, ``:py:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but
+  only display ``get`` as the link text.
 
   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.
@@ -71,6 +78,8 @@ Cross-referencing anything
    :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is
    found, all object types of intersphinx inventories are also searched.
 
+.. _ref-objects:
+
 Cross-referencing objects
 -------------------------
 

doc/usage/restructuredtext/basics.rst

@@ -203,6 +203,8 @@ Two more syntaxes are supported: *CSV tables* and *List tables*. They use an
 Hyperlinks
 ----------
 
+.. _rst-external-links:
+
 External links
 ~~~~~~~~~~~~~~