reST – reStructuredText

A simple markup language for plain text files.

Structural elements

Sectioning

Emacs

C-c C-a or C-=

Format the text above as a title or move it down in the decoration hierarchy.

C-- C-c C-a

Move the title one level up in the hierarchy.

C-c C-h

Display the title decoration hierarchy.

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.

####
Part
####

*******
Chapter
*******

Section
=======

Subsection
----------

Subsubsection
^^^^^^^^^^^^^

Paragraph
"""""""""

Normal paragraphs are separated by a blank line.

Transitions

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

Code for example

Asterisk \*, back-quote \`
and a **mark**\ up.

The following example illustrates special cases:

Asterisk *, back-quote ` and a markup.

Lists

Bullet list

Code for examples

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

  - Sub-item

2. We start with point number 2
#. Automatically numbered item

a) Point a
#) Automatic point b.

   i. Sub
   #. Sub
   #. Sub
   #. Sub

• 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

2. We start with point number 2
3. Automatically numbered item

1. Point a
2. Automatic point b.
   1. Sub
   2. Sub
   3. Sub
   4. Sub

Definition list

Code for example

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

what

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

how

Definition of “how”.

.

Field list

Code for examples

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

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

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

Blocks

Literal Blocks

Code for example

Block one::

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

Another block! ::

   In the text body,
      indentation is
   preserved

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
preserved

Line blocks

Code for example

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

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

Code for example

blah blah blah

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

blah blah blah.

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.

Tables

Simple tables

Code for the examples

==  ==
aA  bB
cC  dD
==  ==

=====  ======
Vokal  Umlaut
=====  ======
aA     äÄ
oO     öÖ
=====  ======

=====  =====  ======
Inputs        Output
------------  ------
  A      B    A or B
=====  =====  ======
False         False
------------  ------
True   False  True
False  True   True
True          True
============  ======

===========  ================
1. Hallo     | blah blah blah
               blah blah blah
               blah
             | blah blah
2. Here      We can wrap the
             text in source
32. There    **aha**
===========  ================

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:

Hallo	blah blah blah blah blah blah blah blah blah
Here	We can wrap the text in source
There	aha

Grid tables

Code for example

+--------+--------+-----------+
| Header | Header with 2 cols |
+========+========+===========+
| A      | Lists: | **C**     |
+--------+  - aha +-----------+
| B::    |  - yes | | a block |
|        |        |   of text |
|  *hey* |  #. hi | | a break |
+--------+--------+-----------+

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

Header	Header with 2 cols
A	Lists: aha yes hi	C
B: *hey*		a block of text a break

Explicit Markup

They all begin with two periods and a white space.

Footnotes

Code for example

In the text [2]_.

.. [2] In the footnote.

First automatic [#]_.
Another automatic [#]_.

.. [#] The first automatic.
.. [#] The other automatic.

A labeled automatic [#one]_.
Another of these [#two]_.

.. [#one] footnote.
.. [#two] labeled footnotes.

An autosymbol [*]_.
More autosymbol [*]_.

.. rubric:: Footnotes
.. [*] footnote.
.. [*] footnotes.

.. [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].

[4]

footnote.

[5]	labeled footnotes.

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

Footnotes

[*]

footnote.

[†]	footnotes.

There is no labeled version of these autosymbol footnotes.

Citations

Code for example

We cite [REL09]_ or REL09_
or even rel09_.

.. [REL09] Citation

.. [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.

[REL09]

Citation

Hypertext links

External

There exist two version for doing this. Either in a citation style or in an inline style.

Code for examples

A link_ in citation style.

.. _link: http://www.google.ch

In-line versions are
`link <http://www.google.ch>`__
or `<http://www.google.ch>`__
or (in Sphinx) http://www.google.ch.

Citation style:

A link in citation style.

In printed documents the link will be listed similar as a citation, as opposed to HTML documents.

In-line style:

In-line versions are link or http://www.google.ch or (in Sphinx) http://www.google.ch.

Note

The syntax `link <URI>`_ produces both a link and a link name as if you would have written .. _link: URI . This means that you can re-reference the same target later in the document as `link`_.

To create an anonymous link (a link without specifying a name) use double underscores `link <URI>`__. This form is necessary if you want many links to have the same name, and it is the preferred form for one-time-used links and for links of the form `<URI>`__.

Internal

To define a label for any text location, precede it with:

.. _‹label›:

plus a blank line. There are two ways of referencing a label.

The Sphinx way (preferred)

To reference ‹label› defined in any document of the project use:

:ref:`‹displayed text› <‹label›>`

If the ‹label› definition is followed by a section title then ‹displayed text› can be omitted and will be replaced by the title. (In this case, the characters < and > also have to be omitted.)

E.g. this section is preceded with .. _internal:, so we have:

:ref:`internal`	Internal
:ref:`This section <internal>`	This section

This is the preferred way because it allows linking across files. E.g. subversion repository URL links to my document on subversion.

In Sphinx it is possible to reference a document as follows

:doc:`reST`

reST – reStructuredText

The reST way

Given a definition of ‹label› has been made in the document, the following will be substituted by ‹label› and link to it:

`‹label›`_

Section titles, footnotes, and citations automatically are link targets. `Internal`_ produces Internal.

Directives

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

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

   ‹body›

reST directives

Table of Contents

Code for example

.. contents:: `This File`
   :depth: 2

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

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

This File

• reST – reStructuredText
  • Structural elements
  • Inline markup
  • Lists
  • Blocks
  • Tables
  • Explicit Markup
  • Directives
  • Sphinx

Include an Image

Code for example

.. image:: wiki.png

.. image:: ‹file name›

Example: the Wikipedia W

General Replacements

Code for examples

.. |W| image:: wiki.png
.. |Wiki| replace:: Wikipedia

The |Wiki| |W|.

.. |‹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 .

Including a reST File

.. include:: ‹file name›

Note

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 for examples

.. raw:: html

   <div align="center">Center</div>

.. raw:: latex

   {\centering Center}

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

.. raw:: ‹writer›

   ‹code›

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

Center

Sphinx directives

Table of Contents

Create a table of contents across several files:

.. toctree::
   :maxdepth: ‹depth›
   :glob:

   ‹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.

Note

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.

Note

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

Code for example

.. image:: wiki.*
   :height: 30pt
   :width: 10pt
   :scale: 90 %
   :alt: distorted W
   :align: center

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.

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

Code for example

.. glossary::

   reST
      re-structured Text

.. glossary::

   ‹reST definition list›

Example:

reST

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›
   :linenos:

   ‹body›

The linenos option switches on line numbering.

Including a File as a Literal Block

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

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

Sidebars

Create a sidebar with ‹Title› and ‹body› which is treated like a document on its own:

.. sidebar:: ‹Title›

   ‹body›

This is how all the example codes in this document are displayed.

Boxed Stuff

Code for example

.. note:: This is a note.

Create a boxed note with ‹text›:

.. note:: ‹text›

Note

This is a note.

Code for example

.. warning:: This is a warning.

Create a boxed warning with ‹text›:

.. warning:: ‹text›

Warning

This is a warning.

Code for example

.. topic:: Attention:

   Always pay attention.

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

.. topic:: ‹title›

   ‹text›

Attention:

Always pay attention.

Code for example

.. seealso::

   `Apples <http://en.wikipedia.org/wiki/Apple>`_
      A kind of fruit.

Create a “see also” box:

.. seealso::

   ‹reST definition list›

See also

Apples

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.

Comments

Code for example

.. Comment
   Even more comment

Not comment anymore

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

Sphinx

Project

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 conf.py and the Makefile.

Math

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 conf.py:

extensions = ['sphinx.ext.pngmath']

Note

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›

Code for example

Pythagoras :math:`a^2+b^2=c^2`

.. math:: \sum_{n=0}^N x_n = y

E.g:

Pythagoras

Multiline Math

Code for example

.. math::

   a+b = c

   b = x_n

   a &= y_n\\
     &= c-b

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.

Code for example

.. math:: \[a = b\]
   :nowrap:

or equivalently:

.. math::
   :nowrap:

   \[a = 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.

or equivalenty

Equation Numbers

Code for example

.. math:: a^2 + b^2 = c^2
   :label: pythag

See equation :eq:`pythag`.

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

:eq:`‹label›`

E.g:

(1)

See equation (1).

Graphics with TikZ

Code for example

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

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

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 conf.py:

extensions = ['sphinx.ext.graphviz']

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

Examples

Undirected graph

.. graph:: foo

   "bar" -- "baz";

Directed graph

.. digraph:: foo

   "bar" -> "baz";