reST – reStructuredText

A simple markup language for plain text files.

Structural elements


Titles are under- (and over-)lined (decorated) by =*-^"~ as below. The exact order of the decoration is not important, the one below is the Python convention.







Normal paragraphs are separated by a blank line.


Any repetition of 4 or more punctuation characters with preceding and trailing blank line is a transition, and looks like this:

Inline markup

*emphasize* emphasize
**emphasize strongly** emphasize strongly
``code`` code
`don't know` don’t know

The following example illustrates special cases:

Asterisk *, back-quote ` and a markup.


Bullet list

  • First item with some lengthy text wrapping hopefully across several lines.
  • Second item
    • Sub-item

Note the blank line before starting a sub-item.

Enumerated list

  1. We start with point number 2
  2. Automatically numbered item
  1. Point a
  2. Automatic point b.
    1. Sub
    2. Sub
    3. Sub
    4. Sub

Definition list

Definition of “what”. We add a few words to show the line wrapping.
Definition of “how”.


Field list

Name:Christoph Reller
Long:Here we insert more text to show the effect of many lines (in Pygments).
Remark:Start on the next line.

Options list

E.g. for listing command line options.

-v An option
-o file Same with value
--delta A long option
--delta=len Same with value


Literal Blocks

A block which is not interpreted at all is preceded by a :: and a blank line. The block must be intended. If no white space is preceding the :: then it is displayed as ”:”.

Block one:

**No** interpretation of
|special| characters.

Another block!

In the text body,
   indentation is

Line blocks

In a line block every line is preceded with | and at least one space.

Line block
New line and we are still on the same line
Yet a new line

Block quotes

The different indentation levels of paragraphs are preserved.

blah blah blah

blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah

blah blah blah.


Simple tables

Tables are preceded and ended with a sequence of “=” to indicate the columns, e.g:

aA bB
cC dD

Headers are indicated by another sequence of “=”, e.g:

Vokal Umlaut
aA äÄ
oO öÖ

Column spans are followed by a sequence of “-” (except for the last header or last row of the table where we must have “=”), e.g:

Inputs Output
A B A or B
False False
True False True
False True True
True True

Table cells are treated like a small document on their own up to line breaks, e.g:

  1. Hallo
blah blah blah blah blah blah blah
blah blah
  1. Here
We can wrap the text in source
  1. There

Grid tables

Grid tables have a more difficult syntax but can express more complex tables.

Header Header with 2 cols
  • aha
  • yes
  1. hi


a block of text
a break

Explicit Markup

They all begin with two periods and a white space.


.. [2] precedes the definition of the footnote 2. It is referenced by [2]_. E.g.

In the text [2].

[2]In the footnote.

First automatic [1]. Another automatic [3].

[1]The first automatic.
[3]The other automatic.

A labeled automatic [4]. Another of these [5].

[5]labeled footnotes.

An autosymbol [*]. More autosymbol [†].



There is no labeled version of these autosymbol footnotes.


.. [REL2009] is followed by the definition of the citation REL2009. It is referenced as [REL2009]_ or REL2009_. Citation labels can contain underlines, hyphens and fullstops. Case is not significant. In Sphinx, definition and reference can reside in different files.

We cite [REL09] or REL09 or even rel09.



Directives are a general-purpose extension mechanism. The general syntax is similar to Explicit Markup:

.. ‹name›:: ‹argument 1›
            ‹argument 2›
   :‹option 1›: ‹value›


reST directives

Table of Contents

Create a table of contents containing (sub)titles ranging from level 1 to level ‹number›:

.. contents:: `‹Title›`
   :depth: ‹number›

Include an Image

.. image:: ‹file name›

Example: the Wikipedia W


General Replacements

.. |‹something›| ‹directive›:: here we define what ‹something› is

here |‹something›| will be replaced by its definition.

Possible ‹directive›s are replace or image. Examples:

The Wikipedia W.

Including a reST File

.. include:: ‹file name›


Don’t use the same file name extension as your source files. Otherwise Sphinx will mistake this file as one of your regular source files.

Raw Code

Code that is meant to appear unprocessed in the output can be written as:

.. raw:: ‹writer›


where ‹writer› is html or latex (or some other output writer) and ‹code› is the actual code to be inserted.


Sphinx directives

Table of Contents

Create a table of contents across several files:

.. toctree::
   :maxdepth: ‹depth›

   ‹file 1 without file name extension›
   ‹file 2 without file name extension›

A glob option enables to use wildcards in the filenames, e.g. /comp/* means all files under the directory comp.


Don’t try to reference the file which contains the toctree directive, otherwise a recursive loop occurs. Use the normal reST table of contents directive instead.


The depth can be further restricted per file by inserting the following Field list type element in the very first line of the file:

:tocdepth: ‹depth›

Include an Image

Basically, this is the same as in pure reST, with the addition that an asterisk (*) can be placed instead of the file extension. In this case, Sphinx will choose the correct file among potentially many depending on the builder (e.g. html or latex) that is currently running.

distorted W

Creating an Index

Entries in the index are created automatically from all information units (like functions, classes or attributes). Explicit manual entries are made as:

.. index:: ‹keyword 1›, ‹keyword 2›, ...

.. index::
   single: ‹keyword›; ‹sub-keyword›

.. index::
   pair: ‹keyword 1st part›; ‹keyword 2nd part›

The first two versions create single (sub-)entries, while the last version creates two entries “‹keyword 1st part›; ‹keyword 2nd part›” and “‹keyword 2nd part›; ‹keyword 1st part›”.

Creating a Glossary

.. glossary::

   ‹reST definition list›


re-structured Text

Code Highlighting

Set Pygment to ‹language› for code highlighting in Literal Blocks globally for the whole file:

.. highlight:: ‹language›
   :linenothreshold: ‹number›

The additional linenothreshold option switches on line numbering for blocks of size beyond ‹number› lines.

Specify the highlighting for a single literal block:

.. code-block:: ‹language›


The linenos option switches on line numbering.

Including a File as a Literal Block

.. literalinclude:: ‹filename›
   :language: ‹language›

The options language and linenos set the highlighting to ‹language› and enables line numbers respectively.

Boxed Stuff

Create a boxed note with ‹text›:

.. note:: ‹text›


This is a note.

Create a boxed warning with ‹text›:

.. warning:: ‹text›


This is a warning.

Create a boxed ‹text› with some ‹title›:

.. topic:: ‹title›



Always pay attention.

Create a “see also” box:

.. seealso::

   ‹reST definition list›

See also

A kind of fruit.

Insert a Title that Does Not Appear in the Contents

Create a title not appearing in the table of contents by:

.. rubric:: ‹Title›

Centered Boldface Text Block

.. centered:: ‹text block›

There are very powerful directives in Sphinx for documenting source code.


Everything starting like a directive with two periods and a space but is followed by normal text is a comment. Mark the indentation in the example:

Not comment anymore



To start a Sphinx project use the interactive sphinx-quickstart command. This will ask you all the necessary questions.You can choose to build with a Makefile.

Customization is done in the file and the Makefile.


There is a mathematical typesetting Sphinx extension called sphinx.ext.pngmath based on LaTeX.

To enable the extension, the following line has to appear in

extensions = ['sphinx.ext.pngmath']


The sphinx.ext.pngmath extension needs dvipng.

You then can type standard LaTeX math expressions, either inline:

:math:`‹LaTeX math expression›`

or in display mode:

.. math::

   ‹LaTeX math expressions›

The second version is also available for a one line expression:

.. math:: ‹1 Line LaTeX math expression›


Pythagoras a^2+b^2=c^2

\sum_{n=0}^N x_n = y

Multiline Math

Sphinx Built-in Mechanism

Several lines of math expressions can be entered by leaving a blank line between them. In addition there is something like an align environment syntax if lines are not separated by a blank line.

a+b = c

b = x_n

a &= y_n\\
  &= c-b

Explicit LaTeX with amsmath mechanism

If the option nowrap is specified then the full LaTeX code (including the math-environment) has to be given. We can assume that the amsmath package is loaded. This is not limited to math typesetting, any LaTeX construct can be rendered in this way.

\[a = b\]

or equivalenty

\[a = b\]

Equation Numbers

Equations are labeled with the label option and referred to using:



(1)a^2 + b^2 = c^2

See equation (1).

Graphics with TikZ

Take a look at my tikz sphinx extension to draw graphics and make plots with the LaTeX package TikZ.

\draw[very thick,double,
fill=blue!40!] (1,2) -- (0,0)
-- (1,0) [rounded corners=4mm]
-- (0,2) -- cycle;

Graphs with Graphviz

There is a graph drawing Sphinx extension based on Graphviz.

To enable the extension we have to add it to the extensions list in

extensions = ['sphinx.ext.graphviz']

On Ubuntu Linux the packages graphviz and libgraphviz4 have to me installed. There is no need to install python-graphviz.


graph foo {
"bar" -- "baz";

digraph foo {
"bar" -> "baz";