1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
Narrative documentation in Sphinx
=================================
Structuring your documentation across multiple pages
----------------------------------------------------
The file ``index.rst`` created by ``sphinx-quickstart`` is the :term:`root
document`, whose main function is to serve as a welcome page and to contain the
root of the "table of contents tree" (or *toctree*). Sphinx allows you to
assemble a project from different files, which is helpful when the project
grows.
As an example, create a new file ``docs/source/usage.rst`` (next to
``index.rst``) with these contents:
.. code-block:: rst
:caption: docs/source/usage.rst
Usage
=====
Installation
------------
To use Lumache, first install it using pip:
.. code-block:: console
(.venv) $ pip install lumache
This new file contains two :ref:`section <rst-sections>` headers, normal
paragraph text, and a :rst:dir:`code-block` directive that renders
a block of content as source code, with appropriate syntax highlighting
(in this case, generic ``console`` text).
The structure of the document is determined by the succession of heading
styles, which means that, by using ``---`` for the "Installation" section
after ``===`` for the "Usage" section, you have declared "Installation" to
be a *subsection* of "Usage".
To complete the process, add a ``toctree`` :ref:`directive <rst-directives>` at
the end of ``index.rst`` including the document you just created, as follows:
.. code-block:: rst
:caption: docs/source/index.rst
Contents
--------
.. toctree::
usage
This step inserts that document in the root of the *toctree*, so now it belongs
to the structure of your project, which so far looks like this:
.. code-block:: text
index
└── usage
If you build the HTML documentation running ``make html``, you will see
that the ``toctree`` gets rendered as a list of hyperlinks, and this allows you
to navigate to the new page you just created. Neat!
.. warning::
Documents outside a *toctree* will result in ``WARNING: document isn't
included in any toctree`` messages during the build process, and will be
unreachable for users.
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 cross-reference, write this sentence right after the
introduction paragraph in ``index.rst``:
.. code-block:: rst
:caption: docs/source/index.rst
Check out the :doc:`usage` section for further information.
The :rst:role:`doc` :ref:`role <rst-roles-alt>` 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 acts as `a target`__.
__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets
For example, to reference the "Installation" subsection, add a label right
before the heading, as follows:
.. code-block:: rst
:caption: docs/source/usage.rst
:emphasize-lines: 4
Usage
=====
.. _installation:
Installation
------------
...
And make the sentence you added in ``index.rst`` look like this:
.. code-block:: rst
:caption: docs/source/index.rst
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. If you do not include an explicit title, hence using
``:ref:`installation```, the section title will be used (in this case,
``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered
as hyperlinks in the HTML documentation.
|
