general improvements to cross-references guide (#7388)

Author: choldgraf

docs/guides/cross-referencing-with-sphinx.rst

@@ -2,26 +2,28 @@ Cross-referencing with Sphinx
 =============================
 
 When writing documentation you often need to link to other pages of your documentation,
-or other sections of the current page, or sections from other pages.
+other sections of the current page, or sections from other pages.
 
 .. _target to paragraph:
 
-An easy way is just to use the final link of the page/section.
+An easy way is just to use the raw URL that Sphinx generates for each page/section.
 This works, but it has some disadvantages:
 
 - Links can change, so they are hard to maintain.
-- Links can be verbose, not easy to know the page/section they are linking to.
-- Not easy way to link to specific sections like paragraphs, figures, or code blocks.
-- It only works for the html version of your documentation.
+- Links can be verbose and hard to read, so it is unclear what page/section they are linking to.
+- There is no easy way to link to specific sections like paragraphs, figures, or code blocks.
+- URL links only work for the html version of your documentation.
 
 ReStructuredText has a built-in way to linking to elements,
 and Sphinx extends this to make it even more powerful!
 Some advantages of using reStructuredText's references:
 
-- Use a name instead of the final link.
+- Use a human-readable name of your choice, instead of a URL.
 - Portable between formats: html, PDF, ePub.
 - Sphinx will warn you of invalid references.
-- Cross reference to more than just pages and sections.
+- You can cross reference more than just pages and section headers.
+
+This page describes some best-practices for cross-referencing with Sphinx.
 
 .. contents:: Table of contents
    :local:
@@ -33,15 +35,20 @@ Some advantages of using reStructuredText's references:
 Explicit targets
 ----------------
 
-If you are not familiar with reStructuredText,
-check :doc:`sphinx:usage/restructuredtext/basics` for a quick introduction.
+.. note::
+
+   If you are not familiar with reStructuredText,
+   check :doc:`sphinx:usage/restructuredtext/basics` for a quick introduction.
 
-In reStructuredText we have targets and references,
-where the target is the place where a reference links to.
+Cross referencing in Sphinx uses two components, **targets** and **references**.
 
-We can reference to any part of a document by adding a target
-in the line before the element we want to link to.
-For example, one way of creating a target to a section is:
+- **references** are pointers in your documentation to other parts of your documentation.
+- **targets** are the where references can point.
+
+You can manually create a target in any location of your documentation, allowing
+you to reference it from other pages. These are called **explicit targets**.
+
+For example, one way of creating an explicit target for a section is:
 
 .. code-block:: rst
 
@@ -53,7 +60,9 @@ For example, one way of creating a target to a section is:
 Then we can reference the section using ```My target`_``,
 that will be rendered as `My target`_.
 
-Another example, a target to a paragraph:
+You can also add explicit targets before paragraphs (or any other part of a page).
+
+Another example, here we add a target to a paragraph:
 
 .. code-block:: rst
 
@@ -66,13 +75,14 @@ Then we can reference it using ```target to paragraph`_``,
 that will be rendered as: `target to paragraph`_.
 
 The reference displays the name of the target by default,
-but we can change that with any text
+but we can use any text you want. For example:
 ```my custom text <target to paragraph>`_``,
 that will be rendered as: `my custom text <target to paragraph>`_.
 
-We can also reference to a place *inside* an element,
-this can be done with an _`inline target`.
-For example, a target inside a paragraph:
+We can also create *in-line targets* within an element on your page,
+allowing you to, for example, reference text *within* a paragraph.
+
+For example, an in-line target inside a paragraph:
 
 .. code-block:: rst
 
@@ -85,9 +95,12 @@ that will be rendered as: `inline target`_.
 Implicit targets
 ----------------
 
+You may also reference sections by name without explicitly giving them one by
+using *implicit targets*.
+
 When we create a section,
 reStructuredText will create a target with the title as the name.
-For example, to reference to the previous section we can use ```Explicit targets`_``,
+For example, to reference the previous section we can use ```Explicit targets`_``,
 that will be rendered as: `Explicit targets`_.
 
 .. note::
@@ -113,7 +126,7 @@ Next we will explore the most common ones.
 The ref role
 ~~~~~~~~~~~~
 
-The ``ref`` role can be used to reference any explicit target.
+The ``ref`` role can be used to reference any explicit target. For example:
 
 .. code-block:: rst
 
@@ -149,9 +162,11 @@ that will be rendered as: :ref:`code <target to code>`.
 The doc role
 ~~~~~~~~~~~~
 
-The `doc` role allow us to link to a page instead of just a section.
-The target name can be a relative or absolute path (without the extension),
-for example to link to a page in the same directory as this one we can use:
+The `doc` role allows us to link to a page instead of just a section.
+The target name can be relative to the page where the role exists, or relative
+to your documentation's root folder (in both cases, you should omit the extension).
+
+For example, to link to a page in the same directory as this one we can use:
 
 .. code-block:: rst
 
@@ -167,21 +182,24 @@ That will be rendered as:
 
 .. tip::
 
-   Using an absolute path is recommend,
-   so we avoid changing the target when the section or page are moved.
+   Using paths relative to your documentation root is recommended,
+   so we avoid changing the target name if the page is moved.
 
 The numref role
 ~~~~~~~~~~~~~~~
 
-The ``numref`` role is used to reference tables and images.
-Add this to your ``conf.py`` file:
+The ``numref`` role is used to reference **numbered** elements of your documentation.
+For example, tables and images.
+
+To activate numbered references, add this to your ``conf.py`` file:
 
 .. code-block:: python
 
    # Enable numref
    numfig = True
 
-In order to use this role we need to create an explicit target to the element.
+Next, ensure that an object you would like to reference has an explicit target.
+
 For example, we can create a target for the next image:
 
 .. _target to image:
@@ -204,18 +222,18 @@ For example, we can create a target for the next image:
 
       Link me!
 
-Then we can reference it using ``:numref:`target to image```,
+Finally, reference it using ``:numref:`target to image```,
 that will be rendered as :numref:`target to image`.
 Sphinx will enumerate the image automatically.
 
-Auto section label
-------------------
+Automatically label sections
+----------------------------
 
-Adding an explicit target on each section and making sure is unique is a big task!
-But Sphinx includes an extension to help us with that problem,
+Manually adding an explicit target to each section and making sure is unique
+is a big task! Fortunately, Sphinx includes an extension to help us with that problem,
 :doc:`autosectionlabel <sphinx:usage/extensions/autosectionlabel>`.
 
-Add this to your ``conf.py`` file:
+To activate the ``autosectionlabel`` extension, add this to your ``conf.py`` file:
 
 .. _target to code:
 
@@ -230,7 +248,7 @@ Add this to your ``conf.py`` file:
    autosectionlabel_prefix_document = True
 
 Sphinx will create explicit targets for all your sections,
-the name of target is the path of the file (without extension) plus the title of the section.
+the name of target has the form ``{path/to/page}:{title-of-section}``.
 
 For example, we can reference the previous section using:
 
@@ -255,24 +273,25 @@ On Read the Docs you can use the :ref:`config-file/v2:sphinx.fail_on_warning` op
 Finding the reference name
 --------------------------
 
-Using names is more descriptive than using a raw link,
-but is still hard to find the correct reference name of an element.
+When you build your documentation, Sphinx will generate an inventory of all
+explicit and implicit links called ``objects.inv``. You can list all of these targets to
+explore what is available for you to reference.
 
-Sphinx allows you to explore all targets with:
+List all targets for built documentation with:
 
 .. prompt:: bash
 
    python -m sphinx.ext.intersphinx <link>
 
-Where the link is the link or local path to your inventory file
+Where the link is either a URL or a local path that points to your inventory file
 (``usually in _build/html/objects.inv``).
-For example, to see all target from the Read the Docs documentation:
+For example, to see all targets from the Read the Docs documentation:
 
 .. prompt:: bash
 
    python -m sphinx.ext.intersphinx https://docs.readthedocs.io/en/stable/objects.inv
 
-More
-----
+Cross-referencing targets in other documentation sites
+------------------------------------------------------
 
 You can reference to docs outside your project too! See :doc:`/guides/intersphinx`.