Make a dedicated section for cross-reference syntax in docs (#12984)

doc/index.rst

@@ -18,7 +18,7 @@ Sphinx
    .. admonition:: 🔗 Powerful Cross-Referencing
       :class: sphinx-feature
 
-      Create :ref:`cross-references <xref-syntax>`
+      Create :ref:`cross-references <xref>`
       within your project,
       and even across :ref:`different projects <ext-intersphinx>`.
       Include references to

doc/tutorial/narrative-documentation.rst

@@ -73,7 +73,7 @@ Adding cross-references
 -----------------------
 
 One powerful feature of Sphinx is the ability to seamlessly add
-:ref:`cross-references <xref-syntax>` to specific parts of the documentation:
+:ref:`cross-references <xref>` to specific parts of the documentation:
 a document, a section, a figure, a code object, etc.  This tutorial is full of
 them!
 

doc/usage/referencing.rst

@@ -1,15 +1,20 @@
-.. _xref-syntax:
+.. _xref:
 
-========================
-Cross-referencing syntax
-========================
+================
+Cross-references
+================
 
 One of Sphinx's most useful features is creating automatic cross-references
 through semantic cross-referencing roles.
 A cross reference to an object description, such as ``:func:`spam```,
 will create a link to the place where ``spam()`` is documented,
 appropriate to each output format (HTML, PDF, ePUB, etc.).
 
+.. _xref-syntax:
+
+Syntax
+------
+
 Sphinx supports various cross-referencing roles to create links
 to other elements in the documentation.
 In general, writing ``:role:`target``` creates a link to

doc/usage/restructuredtext/roles.rst

@@ -18,8 +18,8 @@ They are written as ``:rolename:`content```.
 See :doc:`/usage/domains/index` for roles added by domains.
 
 
-Cross-referencing syntax
-------------------------
+Cross-references
+----------------
 
 See :doc:`/usage/referencing/`.