reStructuredText markup¶

This document describes the custom reStructuredText markup introduced by Sphinx to support SilverStar SCS Documentation and how it should be used.

reStructuredText primer¶

This section is a brief introduction to reStructuredText (reST) concepts and syntax, intended to provide authors with enough information to author documents productively. Since reST was designed to be a simple, unobtrusive markup language, this will not take too long.

Use of whitespace¶

All reST files use an indentation of 3 spaces; no tabs are allowed. The maximum line length is 80 characters for normal text, but tables, deeply indented code samples and long links may extend beyond that. Code example bodies should use normal Python 4-space indentation.

Make use of multiple blank lines where applicable to clarify the structure of the reST file. Extra blank lines help group sections together to make the organization of the file clearer.

A sentence-ending period may be followed by one or two spaces. While reST ignores the second space, it is customarily put in by some users, for example to aid Emacs’ auto-fill mode.

Paragraphs¶

The paragraph is the most basic block in a reST document. Paragraphs are simply chunks of text separated by one or more blank lines. As in Python, indentation is significant in reST, so all lines of the same paragraph must be left-aligned to the same level of indentation.

Inline markup¶

The standard reST inline markup is quite simple: use

one asterisk: *text* for emphasis (italics),
two asterisks: **text** for strong emphasis (boldface), and
backquotes: ``text`` for code samples, variables, and literals.

If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash.

Be aware of some restrictions of this markup:

it may not be nested,
content may not start or end with whitespace: * text* is wrong,
it must be separated from surrounding text by non-word characters. Use a backslash escaped space to work around that: thisis*one*word.

reStructuredText

*text emphasis*
**text strong emphasis**
``Hello World``
thisis\ *one*\ word

Rendered

text emphasis
text strong emphasis
Hello World
thisisoneword

reST also allows for custom “interpreted text roles”, which signify that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is :rolename:`content`.

Lists and Quote-like blocks¶

List markup is natural: just place an asterisk at the start of a paragraph and indent properly. The same goes for numbered lists; they can also be automatically numbered using a # sign.

reStructuredText

* This is a bulleted list.
* It has two items, the second

  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

Rendered

This is a bulleted list.
It has two items, the second

item uses two lines.

This is a numbered list.
It has two items too.
This is a numbered list.
It has two items too.

Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:

reStructuredText

* this is
* a list

   * with a nested list
   * and some subitems

* and here the parent list continues

Rendered

this is
a list
- with a nested list
- and some subitems
and here the parent list continues

Definition lists are created as follows, Note that the term cannot have more than one line of text:

reStructuredText

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

Rendered

term (up to a line of text)

Definition of the term, which must be indented

and can even consist of multiple paragraphs

next term

Description.

Paragraphs are quoted by just indenting them more than the surrounding paragraphs:

Line blocks are a way of preserving line breaks. Line blocks are useful for address blocks, verse (poetry, song lyrics):

reStructuredText

| Do not go gentle into that good night,
| Old age should burn and rave at close of day;
| Rage, rage against the dying of the light.

Rendered

Do not go gentle into that good night,
Old age should burn and rave at close of day;
Rage, rage against the dying of the light.

Literal blocks¶

Literal code blocks are introduced by ending a paragraph with the special marker ::. The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines):

reStructuredText

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

Rendered

This is a normal text paragraph. The next paragraph is a code sample:

It is not processed in any way, except
that the indentation is removed.

It can span multiple lines.

This is a normal text paragraph again.

The handling of the :: marker is smart:

If it occurs as a paragraph of its own, that paragraph is completely left out of the document.
If it is preceded by whitespace, the marker is removed.
If it is preceded by non-whitespace, the marker is replaced by a single colon.

That way, the second sentence in the above example’s first paragraph would be rendered as “The next paragraph is a code sample:”.

Tables¶

For grid tables, you have to “paint” the cell grid yourself. They look like this:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Simple tables are easier to write, but limited: they must contain more than one row, and the first column cells cannot contain multiple lines. They look like this:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Two more syntaxes are supported: CSV tables and List tables. They use an explicit markup block. Refer to Tables for more information.

Hyperlinks¶

External links¶

Use `Link text <http://target>`_ for inline web links. If the link text should be the web address, you don’t need special markup at all, the parser finds links and mail addresses in ordinary text.

Important

There must be a space between the link text and the opening < for the URL.

You can also separate the link and the target definition, like this:

reStructuredText

This is a paragraph that contains `a link`_.

.. _a link: https://domain.invalid/

Rendered

This is a paragraph that contains a link.

Internal links¶

Internal linking is done via a special reST role, see the section on specific markup, Cross-referencing arbitrary locations.

Sections¶

Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

=================
This is a heading
=================

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for the Python documentation, here is a suggested convention:

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

Field Lists¶

Roles¶

A role or “custom interpreted text role” (ref) is an inline piece of explicit markup. It signifies that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is :rolename:`content`.

Docutils supports the following roles:

emphasis – equivalent of *emphasis*
strong – equivalent of **strong**
literal – equivalent of ``literal``
subscript – subscript text
superscript – superscript text
title-reference – for titles of books, periodicals, and other materials

Refer to Roles for roles added by Sphinx.

Explicit markup¶

“Explicit markup” is used in reST for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives.

An explicit markup block begins with a line starting with .. followed by whitespace and is terminated by the next paragraph at the same level of indentation. (There needs to be a blank line between explicit markup and normal paragraphs. This may all sound a bit complicated, but it is intuitive enough when you write it.)

Directives¶

Docutils supports the following directives:

Admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition.
Images: image, figure.
Special tables: table, csv-table, list-table.

Admonitions:

reStructuredText

.. attention::
   attention

.. caution::
   caution

.. danger::
   danger

.. error::
   error

.. Hint::
   Hint

.. important::
   important

.. note::
   note

.. seealso::
   seealso

.. tip::
   tip

.. todo::
   todo

.. warning::
   warning

Rendered

Attention

attention

Caution

caution

Danger

danger

Error

error

Hint

Important

important

Note

note

Images¶

reST supports an image directive, used like so:

.. image:: gnu.png
   (options)

When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image``images/spam.png`` as ../images/spam.png or /images/spam.png.

Footnotes¶

For footnotes, use [#]_ to mark the footnote location, and add the footnote body at the bottom of the document after a “Footnotes” rubric heading, like so:

reStructuredText

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

Rendered

Lorem ipsum [1] dolor sit amet … [2]

Footnotes

Citations¶

Standard reST citations are supported, with the additional feature that they are “global”, i.e. all citations can be referenced from all files. Use them like so:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

Citation usage is similar to footnote usage, but with a label that is not numeric or begins with #.

Substitutions¶

reST supports “substitutions”, which are pieces of text and/or markup referred to in the text by |name|. They are defined like footnotes with explicit markup blocks, like this:

reStructuredText

.. |name| replace:: replacement *text*

Substitutions: |name|

Rendered

Substitutions: replacement text

If you want to use some substitutions for all documents, put them into rst_prolog or rst_epilog or put them into a separate file and include it into all documents you want to use them in, using the include directive. (Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.)

Comments¶

Every explicit markup block (starting with ..) which isn’t a valid markup construct is regarded as a comment:

.. This is a comment.

You can indent text after a comment start to form multiline comments:

..
   This whole indented block
   is a comment.

   Still in the comment.

Gotchas¶

There are some problems one commonly runs into while authoring reST documents:

Separation of inline markup: As said above, inline markup spans must be separated from the surrounding text by non-word characters, you have to use an escaped space to get around that.
No nested inline markup: Something like *see :func:`foo`* is not possible.

Directives¶

As previously discussed, a directive is a generic block of explicit markup. While Docutils provides a number of directives, Sphinx provides many more and uses directives as one of the primary extension mechanisms.

See Domains for roles added by domains.

Table-of-contents markup¶

Since reST does not have facilities to interconnect several documents, or split documents into multiple output files, Sphinx uses a custom directive to add relations between the single files the documentation is made of, as well as tables of contents. The toctree directive is the central element.

toctree

This directive inserts a “TOC tree” at the current location, using the individual TOCs (including “sub-TOC trees”) of the files given in the directive body. A numeric maxdepth option may be given to indicate the depth of the tree; by default, all levels are included.

Consider this example (taken from the library reference index):

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more files listed here)

This accomplishes two things:

Tables of contents from all those files are inserted, with a maximum depth of two, that means one nested heading. toctree directives in those files are also taken into account.
Sphinx knows that the relative order of the files intro, strings and so forth, and it knows that they are children of the shown file, the library index. From this information it generates “next chapter”, “previous chapter” and “parent chapter” links.

In the end, all files included in the build process must occur in one toctree directive; Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not be reachable through standard navigation.

The special file contents.rst at the root of the source directory is the “root” of the TOC tree hierarchy; from it the “Contents” page is generated.

Paragraph-level markup¶

These directives create short paragraphs and can be used inside information units as well as normal text:

note

An especially important bit of information about an API that a user should be aware of when using whatever bit of API the note pertains to. The content of the directive should be written in complete sentences and include all appropriate punctuation.

Example:

.. note::

   This function is not suitable for sending spam e-mails.

warning: An important bit of information about an API that a user should be aware of when using whatever bit of API the warning pertains to. The content of the directive should be written in complete sentences and include all appropriate punctuation. In the interest of not scaring users away from pages filled with warnings, this directive should only be chosen over note for information regarding the possibility of crashes, data loss, or security implications.

versionadded

This directive documents the version of the project which added the described feature to the library or C API. When this applies to an entire module, it should be placed at the top of the module section before any prose.

The first argument must be given and is the version in question; you can add a second argument consisting of a brief explanation of the change.

Example:

.. function:: func()

   Return foo and bar.

   .. versionadded:: 3.5

Note that there must be no blank line between the directive head and the explanation; this is to make these blocks visually continuous in the markup.

versionchanged

Similar to versionadded, but describes when and what changed in the named feature in some way (new parameters, changed side effects, platform support, etc.). This one must have the second argument (explanation of the change).

Example:

.. function:: func(spam=False)

   Return foo and bar, optionally with *spam* applied.

   .. versionchanged:: 3.6
      Added the *spam* parameter.

Note that there should be no blank line between the directive head and the explanation; this is to make these blocks visually continuous in the markup.

deprecated

Indicates the version from which the described feature is deprecated.

There is one required argument: the version from which the feature is deprecated.

Example:

.. deprecated:: 3.8

deprecated-removed

Like deprecated, but it also indicates in which version the feature is removed.

There are two required arguments: the version from which the feature is deprecated, and the version in which the feature is removed.

Example:

.. deprecated-removed:: 3.8 4.0

impl-detail

This directive is used to mark CPython-specific information. Use either with a block content or a single sentence as an argument, i.e. either

.. impl-detail::

   This describes some implementation detail.

   More explanation.

.. impl-detail:: This shortly mentions an implementation detail.

“CPython implementation detail:“ is automatically prepended to the content.

seealso

Many sections include a list of references to module documentation or external documents. These lists are created using the seealso directive.

The seealso directive is typically placed in a section just before any sub-sections. For the HTML output, it is shown boxed off from the main flow of the text.

The content of the seealso directive should be a reST definition list. Example:

.. seealso::

   Module :mod:`zipfile`
      Documentation of the :mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.

rubric: This directive creates a paragraph heading that is not used to create a table of contents node. It is currently used for the “Footnotes” caption.

centered

This directive creates a centered boldfaced paragraph. Use it as follows:

.. centered::

   Paragraph contents.

Showing code examples¶

Examples of Python source code or interactive sessions are represented using standard reST literal blocks. They are started by a :: at the end of the preceding paragraph and delimited by indentation.

Representing an interactive session requires including the prompts and output along with the Python code. No special markup is required for interactive sessions. After the last line of input or output is presented, there should be no trailing prompt. An example of correct usage is: >>> 1 + 1

Some more Ruby code.

Syntax highlighting is handled in a smart way:

There is a “highlighting language” for each source file. By default, this is 'python' as the majority of files will have to highlight Python snippets.
Within Python highlighting mode, interactive sessions are recognized automatically and highlighted appropriately.
The highlighting language can be changed using the highlight directive, used as follows:
```
.. highlight:: c
```
This language is used until the next highlight directive is encountered.

The code-block directive can be used to specify the highlight language of a single code block, e.g.:

.. code-block:: c

   #include <stdio.h>

   void main() {
       printf("Hello world!\n");
   }

The values normally used for the highlighting language are:
- python (the default)
- c
- rest
- none (no highlighting)
If highlighting with the current language fails, the block is not highlighted in any way.

Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the literalinclude directive. For example, to include the Python source file example.py, use:

.. literalinclude:: example.py

The file name is relative to the current file’s path. Documentation-specific include files should be placed in the Doc/includes subdirectory.

Glossary¶

glossary

This directive must contain a reST definition-list-like markup with terms and definitions. The definitions will then be referenceable with the``term`` role. Example:

.. glossary::

   environment
      A structure where information about all documents under the root is
      saved, and used for cross-referencing.  The environment is pickled
      after the parsing stage, so that successive runs only need to read
      and parse new and changed documents.

   source directory
      The directory which, including its subdirectories, contains all
      source files for one Sphinx project.

Meta-information markup¶

sectionauthor

Identifies the author of the current section. The argument should include the author’s name such that it can be used for presentation (though it isn’t) and email address. The domain name portion of the address should be lower case. Example:

.. sectionauthor:: Guido van Rossum <guido@python.org>

Currently, this markup isn’t reflected in the output in any way, but it helps keep track of contributions.

Math¶

The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no further translation is necessary when building LaTeX output.

math

Directive for displayed math (math that takes the whole line for itself).

The directive supports multiple equations, which should be separated by a blank line:

reStructuredText

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

Rendered

\[ \begin{align}\begin{aligned}(a + b)^2 = a^2 + 2ab + b^2\\(a - b)^2 = a^2 - 2ab + b^2\end{aligned}\end{align} \]

In addition, each single equation is set within a split environment, which means that you can have multiple aligned lines in an equation, aligned at & and separated by \\:

reStructuredText

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

Rendered

\[\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\]

For more details, look into the documentation of the AmSMath LaTeX package.

When the math is only one line of text, it can also be given as a directive argument:

.. math:: (a + b)^2 = a^2 + 2ab + b^2

Normally, equations are not numbered. If you want your equation to get a number, use the label option. When given, it selects an internal label for the equation, by which it can be cross-referenced, and causes an equation number to be issued. See role eq for an example. The numbering style depends on the output format.

There is also an option nowrap that prevents any wrapping of the given math in a math environment. When you give this option, you must make sure yourself that the math is properly set up. For example:

reStructuredText

.. math::
   :nowrap:

   \begin{eqnarray}
      y    & = & ax^2 + bx + c \\
      f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}

Rendered

\begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}

reStructuredText markup¶

reStructuredText primer¶

Use of whitespace¶

Paragraphs¶

Inline markup¶

Lists and Quote-like blocks¶

Literal blocks¶

Tables¶

Hyperlinks¶

External links¶

Internal links¶

Sections¶

Field Lists¶

Roles¶

Explicit markup¶

Directives¶

Images¶

Footnotes¶

Citations¶

Substitutions¶

Comments¶

Gotchas¶

Roles¶

Cross-referencing syntax¶

Cross-referencing arbitrary locations¶

Cross-referencing documents¶

Referencing downloadable files¶

Cross-referencing figures by figure number¶

Cross-referencing other items of interest¶

Inline code highlighting¶

Math¶

Other semantic markup¶

Index-generating markup¶

Substitutions¶

Directives¶

Table-of-contents markup¶

Paragraph-level markup¶

Showing code examples¶

Glossary¶

Meta-information markup¶

Math¶