.. include:: /include/substitutions.txt
.. include:: /include/external_links.txt
.. include:: /include/custom_roles.txt
***************
Explicit Markup
***************
Comments
********
Arbitrary indented text may follow the explicit markup start and will be processed as
a comment element, and not included in the output. The comment ends when indented
characters return to the same indent level as the ``..`` that started the comment.
.. code-block:: rst
..
_This: is a comment.
The above is a comment because empty space after the .. is not recognized as a
directive.
..
[and] this.
..
this:: too.
..
|even| this:: .
.. Anything not recognized as an explicit directive by the Docutils + Sphinx
parers is treated as a comment.
.. [this] however, is a citation.
See comments_ for more information.
Directives
**********
.. code-block:: rst
.. directive_name:: <-- two colons
:config_option: <-- config options when available
text block the directive applies to
Sidebars
********
Sidebars are like miniature, parallel documents that occur inside other documents,
providing related or reference material. A sidebar is typically offset by a border
and "floats" to the side of the page; the document's main text may flow around it.
Sidebars can also be likened to super-footnotes; their content is outside of the flow
of the document's main text.
Sidebars may occur anywhere a section or transition may occur. Body elements
(including sidebars) may not contain nested sidebars.
Typically the content of these is information relevant to something on the page, the
whole page, or to the whole document if it is presented on the landing page.
The floating rectangular "window" normally appears to the right of whatever content on
the page is immediately below the ``.. sidebar::`` directive. However, exactly where
and how it appears is up to the theme being employed. Here is an example. Links to
sections below this one are used for convenience, but it can literally be any type
of content.
The directive's sole argument is interpreted as the sidebar title, which may be
followed by a subtitle option (see below); the next line must be blank. All
subsequent lines make up the sidebar body, interpreted as body elements. For
example:
.. code-block:: rst
.. sidebar:: Quick References
:subtitle: ...and other pages
Here is a set of quick links to help you quickly navigate
to what you are looking for:
- :ref:`explicit glossaries`
- :ref:`explicit footnotes`
- :ref:`explicit citations`
- :ref:`explicit figure references`
- :ref:`explicit further reading`
- :doc:`hyperlinks`
And here is what it looks like when it is rendered. Note that it appears to the
side of whatever is just below it. This is the HTML that the above reST source
generates. You can also override the theme if you choose and use your ``custom.css``
file to make it appear any way you want it to.
.. code-block:: html
.. sidebar:: Quick References
:subtitle: ...and other pages
Here is a set of quick links to help you quickly navigate
to what you are looking for:
- :ref:`explicit glossaries`
- :ref:`explicit footnotes`
- :ref:`explicit citations`
- :ref:`explicit figure references`
- :ref:`explicit further reading`
- :doc:`hyperlinks`
.. _explicit glossaries:
Glossaries
**********
Glossaries are plain definition lists as "content" of a ``.. glossary::`` directive.
The terms can be later linked to from elsewhere in the Sphinx build using an in-line
``:term:`` interpreted text role.
Example source:
.. code-block:: rst
.. glossary::
term1
words of definition 1
term2
words of definition 2
...(in text elsewhere in the Sphinx build)...
Use a :term:`term1` when this situation arises. It pleasantly offers a link to
the definition for readers who need it, and readers who don't need it can simply
read on.
These are also encapsulated in ``
`` elements with the unique trait that the
``
`` element has a class attribute: ``glossary``, which makes it easy to format
with CSS.
When they are rendered, they look like this:
.. glossary::
term1
words of definition 1
term2
words of definition 2
...(in text elsewhere in the Sphinx build)...
Use a :term:`term1` when this situation arises. It pleasantly offers a link to
the definition for readers who need it, and readers who don't need it can simply
read on.
.. _explicit footnotes:
Footnotes
*********
Footnotes are created the usual way for reStructuredText documented in the
`reST Footnotes Specification `_.
Example source:
.. code-block:: rst
Some paragraph text with a footnote. [1]_ Some additional paragraph text\ [2]_.
Some more paragraph text\ [3]_. And some more paragraph text\ [4]_.
...
.. [1]
This is the contents of the footnote, which might be long.
.. [2] This is an example of a multi-line footnote showing how
indentation needs to be handled so it can be parsed
correctly by the DocUtils parser.
.. [3] This is another example of a multi-line footnote
showing how indentation can be different for subsequent
lines in the paragraph.
Additional paragraphs must be indented identically.
.. [4] This is a second example of a multi-line footnote
showing how indentation can be different for subsequent
lines in the paragraph.
This is what happens when subsequent paragraphs are not
indented identically. It doesn't work. So don't do it.
Note that the reference *must* be preceded by a space. If the hyperlinked footnote
symbol should be against the word before it, then escape the preceeding space like
this: ``footnoted topic\ [1]_``.
This is what it looks like when it is rendered.
Some paragraph text with a footnote. [1]_ Some additional paragraph text\ [2]_.
Some more paragraph text\ [3]_. And some more paragraph text\ [4]_.
...
.. [1]
This is the contents of the footnote, which might be long.
.. [2] This is an example of a multi-line footnote showing how
indentation needs to be handled so it can be parsed
correctly by the DocUtils parser.
.. [3] This is another example of a multi-line footnote
showing how indentation can be different for subsequent
lines in the paragraph.
Additional paragraphs must be indented identically.
.. [4] This is a second example of a multi-line footnote
showing how indentation can be different for subsequent
lines in the paragraph.
This is what happens when subsequent paragraphs are not
indented identically. It doesn't work. So don't do it.
More Footnote Syntax
====================
.. code-block:: rst
Lorem ipsum\ [5]_ dolor sit amet, consectetur adipiscing elit\ [#unique_name]_,
sed do eiusmod tempor [#]_ incididunt ut labore et dolore magna aliqua.
Ut enim\ [*]_ ad minim veniam, quis nostrud.... This is my book.\ [BOOK2026]_
.. rubric:: Footnotes <-- optional
.. [BOOK2026]
Citation text
.. [5] <-- manually-numbered footnote (directives DO NOT have to be in same sequence, but should be)
.. [#unique_name] <-- auto-numbered label (directives DO NOT have to be in same sequence)
.. [#] <-- auto-numbered footnote (starts at 1) (directives have to be in same sequence)
.. [*] <-- auto-symbol footnote (directives have to be in same sequence)
Renders like this:
Lorem ipsum\ [5]_ dolor sit amet, consectetur adipiscing elit\ [#unique_name]_,
sed do eiusmod tempor [#]_ incididunt ut labore et dolore magna aliqua.
Ut enim\ [*]_ ad minim veniam, quis nostrud.... This is my book.\ [BOOK2026]_
.. rubric:: Footnotes <-- optional
.. [BOOK2026]
Citation text
.. [5] <-- manually-numbered footnote (directives DO NOT have to be in same sequence, but should be)
.. [#unique_name] <-- auto-numbered label (directives DO NOT have to be in same sequence)
.. [#] <-- auto-numbered footnote (starts at 1) (directives have to be in same sequence)
.. [*] <-- auto-symbol footnote (directives have to be in same sequence)
:u:`Manually-Numbered` footnotes and :u:`Auto-Numbered Label` footnotes both can have
any number of references (links) to 1 footnote.
In contrast, :u:`Auto-Numbered` footnote and :u:`Auto-Symbol` footnotes both require a
1:1 connection with the actual footnotes: one reference to one footnote, and in both
cases the footnotes must appear in the same sequence as the references. For this
reason, they cannot be used when more than one reference is needed. These are okay
for "quickie" uses where the number of footnotes is small and the document will not
undergo a lot of changes in its lifetime. However, for more complex documents,
especially those that will undergo many changes in its lifetime, these two types of
footnotes are not recommended (by this author) due to the maintenance liability
(e.g. when paragraphs or rows in a table are moved around in a document).
:u:`Manually-Numbered` footnotes and :u:`Auto-Numbered Label` do not carry this
liability.
Footnote text must be consistently indented and left-aligned. The first body element
within a footnote may begin on the same line as the footnote label. However, if the
first element fits on one line and the indentation of the remaining elements differ,
the first element must begin on the line after the footnote label. Otherwise, the
difference in indentation will not be detected.
Footnotes may occur anywhere in the document, not only at the end. Where and how
they appear in the processed output depends on the processing system.
Prior to Sphinx v8.0(?), Sphinx rendered them to ``
`` with the footnote label
(and link) as the "term" part, and the content as the "definition" part.
So the Furo theme having separate ``
`` formatting for footnotes appears to be
there to be compatible with older versions of Sphinx.
As of Sphinx version 8.0(?), Sphinx renders a list of footnotes as a list of
``