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
130
|
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 :duref:`a target <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.
What about :doc:`documenting code objects in Sphinx </tutorial/describing-code>`?
Read on!
|
