Skip to content

Commit 1a5505f

Browse files
authored
Merge pull request #7326 from readthedocs/cross-reference-guide
Guide: Cross-referencing with Sphinx
2 parents a8e817e + 0669609 commit 1a5505f

File tree

4 files changed

+311
-8
lines changed

4 files changed

+311
-8
lines changed

docs/conf.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,8 @@ def get_version():
110110
# Activate autosectionlabel plugin
111111
autosectionlabel_prefix_document = True
112112

113+
numfig = True
114+
113115
# sphinx-notfound-page
114116
# https://github.com/readthedocs/sphinx-notfound-page
115117
notfound_context = {
Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
Cross-referencing with Sphinx
2+
=============================
3+
4+
When writing documentation you often need to link to other pages of your documentation,
5+
other sections of the current page, or sections from other pages.
6+
7+
.. _target to paragraph:
8+
9+
An easy way is just to use the raw URL that Sphinx generates for each page/section.
10+
This works, but it has some disadvantages:
11+
12+
- Links can change, so they are hard to maintain.
13+
- Links can be verbose and hard to read, so it is unclear what page/section they are linking to.
14+
- There is no easy way to link to specific sections like paragraphs, figures, or code blocks.
15+
- URL links only work for the html version of your documentation.
16+
17+
reStructuredText has a built-in way to linking to elements,
18+
and Sphinx extends this to make it even more powerful!
19+
Some advantages of using reStructuredText's references:
20+
21+
- Use a human-readable name of your choice, instead of a URL.
22+
- Portable between formats: html, PDF, ePub.
23+
- Sphinx will warn you of invalid references.
24+
- You can cross reference more than just pages and section headers.
25+
26+
This page describes some best-practices for cross-referencing with Sphinx.
27+
28+
.. contents:: Table of contents
29+
:local:
30+
:backlinks: none
31+
:depth: 3
32+
33+
Getting started
34+
---------------
35+
36+
.. _My target:
37+
38+
Explicit targets
39+
~~~~~~~~~~~~~~~~
40+
41+
.. note::
42+
43+
If you are not familiar with reStructuredText,
44+
check :doc:`sphinx:usage/restructuredtext/basics` for a quick introduction.
45+
46+
Cross referencing in Sphinx uses two components, **references** and **targets**.
47+
48+
- **references** are pointers in your documentation to other parts of your documentation.
49+
- **targets** are where the references can point to.
50+
51+
You can manually create a *target* in any location of your documentation, allowing
52+
you to *reference* it from other pages. These are called **explicit targets**.
53+
54+
For example, one way of creating an explicit target for a section is:
55+
56+
.. code-block:: rst
57+
58+
.. _My target:
59+
60+
Explicit targets
61+
~~~~~~~~~~~~~~~~
62+
63+
Then we can reference the section using ```My target`_``,
64+
that will be rendered as `My target`_.
65+
66+
You can also add explicit targets before paragraphs (or any other part of a page).
67+
68+
Another example, here we add a target to a paragraph:
69+
70+
.. code-block:: rst
71+
72+
.. _target to paragraph:
73+
74+
An easy way is just to use the final link of the page/section.
75+
This works, but it has some disadvantages:
76+
77+
Then we can reference it using ```target to paragraph`_``,
78+
that will be rendered as: `target to paragraph`_.
79+
80+
The reference displays the name of the target by default,
81+
but we can use any text you want. For example:
82+
```my custom text <target to paragraph>`_``,
83+
that will be rendered as: `my custom text <target to paragraph>`_.
84+
85+
We can also create _`in-line targets` within an element on your page,
86+
allowing you to, for example, reference text *within* a paragraph.
87+
88+
For example, an in-line target inside a paragraph:
89+
90+
.. code-block:: rst
91+
92+
We can also create _`in-line targets` within an element on your page,
93+
allowing you to, for example, reference text *within* a paragraph.
94+
95+
Then we can reference it using ```in-line targets`_``,
96+
that will be rendered as: `in-line targets`_.
97+
98+
Implicit targets
99+
~~~~~~~~~~~~~~~~
100+
101+
You may also reference sections by name without explicitly giving them one by
102+
using *implicit targets*.
103+
104+
When we create a section,
105+
reStructuredText will create a target with the title as the name.
106+
For example, to reference the previous section we can use ```Explicit targets`_``,
107+
that will be rendered as: `Explicit targets`_.
108+
109+
.. note::
110+
111+
`Footnotes <https://docutils.sourceforge.io/docs/user/rst/quickref.html#footnotes>`_ and
112+
`citations <https://docutils.sourceforge.io/docs/user/rst/quickref.html#citations>`_
113+
also create implicit targets.
114+
115+
Cross-referencing using roles
116+
-----------------------------
117+
118+
All targets that we have seen so far can be referenced only from the same page.
119+
Sphinx provides some roles that allows us to reference any explicit target from any page.
120+
121+
.. note::
122+
123+
Since Sphinx will make all explicit targets available globally,
124+
all targets must be unique.
125+
126+
You can see the complete list of cross-referencing roles at :ref:`sphinx:xref-syntax`.
127+
Next, we will explore the most common ones.
128+
129+
The ref role
130+
~~~~~~~~~~~~
131+
132+
The ``ref`` role can be used to reference any explicit target. For example:
133+
134+
.. code-block:: rst
135+
136+
- :ref:`my target`.
137+
- :ref:`Target to paragraph <target to paragraph>`.
138+
- :ref:`Target inside a paragraph <in-line targets>`.
139+
140+
That will be rendered as:
141+
142+
- :ref:`my target`.
143+
- :ref:`Target to paragraph <target to paragraph>`.
144+
- :ref:`Target inside a paragraph <in-line targets>`.
145+
146+
The ``ref`` role also allow us to reference code blocks:
147+
148+
.. code-block:: rst
149+
150+
.. _target to code:
151+
152+
.. code-block:: python
153+
154+
# Add the extension
155+
extensions = [
156+
'sphinx.ext.autosectionlabel',
157+
]
158+
159+
# Make sure the target is unique
160+
autosectionlabel_prefix_document = True
161+
162+
We can reference it using ``:ref:`code <target to code>```,
163+
that will be rendered as: :ref:`code <target to code>`.
164+
165+
The doc role
166+
~~~~~~~~~~~~
167+
168+
The `doc` role allows us to link to a page instead of just a section.
169+
The target name can be relative to the page where the role exists, or relative
170+
to your documentation's root folder (in both cases, you should omit the extension).
171+
172+
For example, to link to a page in the same directory as this one we can use:
173+
174+
.. code-block:: rst
175+
176+
- :doc:`intersphinx`
177+
- :doc:`/guides/intersphinx`
178+
- :doc:`Custom title </guides/intersphinx>`
179+
180+
That will be rendered as:
181+
182+
- :doc:`intersphinx`
183+
- :doc:`/guides/intersphinx`
184+
- :doc:`Custom title </guides/intersphinx>`
185+
186+
.. tip::
187+
188+
Using paths relative to your documentation root is recommended,
189+
so we avoid changing the target name if the page is moved.
190+
191+
The numref role
192+
~~~~~~~~~~~~~~~
193+
194+
The ``numref`` role is used to reference **numbered** elements of your documentation.
195+
For example, tables and images.
196+
197+
To activate numbered references, add this to your ``conf.py`` file:
198+
199+
.. code-block:: python
200+
201+
# Enable numref
202+
numfig = True
203+
204+
Next, ensure that an object you would like to reference has an explicit target.
205+
206+
For example, we can create a target for the next image:
207+
208+
.. _target to image:
209+
210+
.. figure:: /img/logo.png
211+
:alt: Logo
212+
:align: center
213+
:width: 240px
214+
215+
Link me!
216+
217+
.. code-block:: rst
218+
219+
.. _target to image:
220+
221+
.. figure:: /img/logo.png
222+
:alt: Logo
223+
:align: center
224+
:width: 240px
225+
226+
Link me!
227+
228+
Finally, reference it using ``:numref:`target to image```,
229+
that will be rendered as :numref:`target to image`.
230+
Sphinx will enumerate the image automatically.
231+
232+
Automatically label sections
233+
----------------------------
234+
235+
Manually adding an explicit target to each section and making sure is unique
236+
is a big task! Fortunately, Sphinx includes an extension to help us with that problem,
237+
:doc:`autosectionlabel <sphinx:usage/extensions/autosectionlabel>`.
238+
239+
To activate the ``autosectionlabel`` extension, add this to your ``conf.py`` file:
240+
241+
.. _target to code:
242+
243+
.. code-block:: python
244+
245+
# Add the extension
246+
extensions = [
247+
'sphinx.ext.autosectionlabel',
248+
]
249+
250+
# Make sure the target is unique
251+
autosectionlabel_prefix_document = True
252+
253+
Sphinx will create explicit targets for all your sections,
254+
the name of target has the form ``{path/to/page}:{title-of-section}``.
255+
256+
For example, we can reference the previous section using:
257+
258+
.. code-block:: rst
259+
260+
- :ref:`guides/cross-referencing-with-sphinx:explicit targets`.
261+
- :ref:`Custom title <guides/cross-referencing-with-sphinx:explicit targets>`.
262+
263+
That will be rendered as:
264+
265+
- :ref:`guides/cross-referencing-with-sphinx:explicit targets`.
266+
- :ref:`Custom title <guides/cross-referencing-with-sphinx:explicit targets>`.
267+
268+
Invalid targets
269+
---------------
270+
271+
If we reference an invalid or undefined target Sphinx will warn us.
272+
You can use the :option:`-W <sphinx:sphinx-build.-W>` option when building your docs
273+
to fail the build if there are any invalid references.
274+
On Read the Docs you can use the :ref:`config-file/v2:sphinx.fail_on_warning` option.
275+
276+
Finding the reference name
277+
--------------------------
278+
279+
When you build your documentation, Sphinx will generate an inventory of all
280+
explicit and implicit links called ``objects.inv``. You can list all of these targets to
281+
explore what is available for you to reference.
282+
283+
List all targets for built documentation with:
284+
285+
.. prompt:: bash
286+
287+
python -m sphinx.ext.intersphinx <link>
288+
289+
Where ``<link>`` is either a URL or a local path that points to your inventory file
290+
(usually in ``_build/html/objects.inv``).
291+
For example, to see all targets from the Read the Docs documentation:
292+
293+
.. prompt:: bash
294+
295+
python -m sphinx.ext.intersphinx https://docs.readthedocs.io/en/stable/objects.inv
296+
297+
Cross-referencing targets in other documentation sites
298+
------------------------------------------------------
299+
300+
You can reference to docs outside your project too! See :doc:`/guides/intersphinx`.

docs/guides/tools.rst

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,13 @@ These guides will help you get the most out of your documentation authoring tool
55
whether that is Sphinx or MkDocs.
66

77
.. toctree::
8-
:maxdepth: 1
8+
:maxdepth: 1
99

10-
adding-custom-css
11-
intersphinx
12-
manage-translations
13-
mkdocs-old-versions
14-
pdf-non-ascii-languages
15-
remove-edit-buttons
16-
vcs
10+
adding-custom-css
11+
cross-referencing-with-sphinx
12+
intersphinx
13+
manage-translations
14+
mkdocs-old-versions
15+
pdf-non-ascii-languages
16+
remove-edit-buttons
17+
vcs

docs/img/logo.png

20 KB
Loading

0 commit comments

Comments
 (0)