From e022872f3ba5e59c965e7b9b89c9479c807426b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Luis=20Cano=20Rodr=C3=ADguez?= <hello@juanlu.space>
Date: Thu, 17 Jun 2021 00:37:32 +0200
Subject: [PATCH] Add section about cross-references

---
 doc/tutorial/index.rst | 50 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst
index bd0731b87..c4de85cc5 100644
--- a/doc/tutorial/index.rst
+++ b/doc/tutorial/index.rst
@@ -382,6 +382,56 @@ just created.  Neat!
    linked from anywhere (therefore it will not be discoverable), whereas for
    the PDF builder, it will not be included at all.
 
+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:
+a document, a section, a figure, a code object, etc.  This tutorial is full of
+them!
+
+To add a straightforward cross-reference, write this sentence right after the
+introduction paragraph in ``index.rst``:
+
+.. code-block:: rest
+
+   Check out the :doc:`usage` section for further information.
+
+The :rst:role:`doc` role you used automatically references a specific document
+in the project, in this case the ``usage.rst`` you created earlier.
+
+Alternatively, you can also add a cross-reference to an arbitrary part of the
+project. For that, you need to use the :rst:role:`ref` role, and add an
+explicit *label* that can act as a target.
+
+For example, to reference the "Installation" subsection, add a label right
+before the heading, as follows:
+
+.. code-block:: rest
+
+   Usage
+   =====
+
+   .. _installation:
+
+   Installation
+   ------------
+
+   ...
+
+And make the sentence you added in ``index.rst`` look like this:
+
+.. code-block:: rest
+
+   Check out the :doc:`usage` section for further information, including how to
+   :ref:`install <installation>` the project.
+
+Notice a trick here: the ``install`` part specifies how the link will look like
+(we want it to be a specific word, so the sentence makes sense), whereas the
+``<installation>`` part refers to the actual label we want to add a
+cross-reference to. Both the ``:doc:`` and the ``:ref:`` roles will be rendered
+as hyperlinks in the HTML documentation.
+
 Where to go from here
 ---------------------