1. Restructured Text (reST) and Sphinx CheatSheet ¶

Overview

This page describes some of the RST and Sphinx syntax. It is based on resource found at Sphinx , Docutils and more generally software documentation written with Sphinx.

Date:	July 27, 2011
Author:	Thomas Cokelaer

Contents

1.1. Introduction ¶

The reStructuredText (RST) syntax provides an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. However, you need to be very precise and stick to some strict rules:

like Python, RST syntax is sensitive to indentation !

RST requires blank lines between paragraphs

This entire document is written with the RST syntax. At the bottom of the right sidebar, you should find a link to the source, which is a good starting point.

1.2. Inline markup and special characters (e.g., bold, italic, verbatim)¶

The * is a special character used to defined bold and italic text:

syntax	HTML rendering
italic	italic
italic	bold

The backquote ` is another special character. For instance, it is used to create links to external web pages, as you will see in section Internal and External Links:

`My home page <your-prefered-page.info>`_

The double backquote is used to enter in verbatim mode.

syntax	HTML rendering
``**``	`**`

Here are some restrictions about the * and `` syntax. They

cannot 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 like a space.

The use of backslash is a work around to second previous restrictions about whitespaces in the following case:

this is a *longish* paragraph is correct and gives longish.

this is a long*ish* paragraph is not interpreted as expected. You should use this is a long\ *ish* paragraph to obtain longish paragraph

In Python docstrings it will be necessary to escape any backslash characters so that they actually reach reStructuredText. The simplest way to do this is to use raw strings by adding the letter r in front of the docstring.

Python string	Typical result
r"""\escape \`with` "\\""""	escape `with` "\"
"""\\escape \\`with` "\\\\""""	escape `with` "\"
"""\escape \`with` "\\""""	`escape with ""`

Todo

check this table contents

1.3. Headings ¶

In order to write a title, you can either underline it or under and overline it:

*****
Title
*****

subtitle
########

subsubtitle
***********
and so on

Two rules:

If under and overline are used, their length must be identical

The length of the underline must be at least as long as the title itself

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, it is better to stick to the same convention throughout a project. For instance:

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

1.4. Internal and External Links ¶

In Sphinx, you have 3 type of links:

External links (http-like)
Implicit links to title
Explicit links to user-defined label (e.g., to refer to external titles).

1.4.1. External links¶

If you want to create a link to a website, the syntax is

`<http://www.python.org/>`_

which appear as http://www.python.org/ . Note the underscore after the final single quote. Since the full name of the link is not always simple or meaningful, you can specify a label (note the space between the label and link name):

`Python <http://www.python.org/>`_

The rendering is now: Python.

Note

If you have an underscore within the label/name, you got to escape it with a ‘\’ character.

1.4.2. Implicit Links to Titles¶

All titles are considered as hyperlinks. A link to a title is just its name within quotes and a final underscore:

`Internal and External links`_

This syntax works only if the title and link are within the same RST file. If this is not the case, then you need to create a label before the title and refer to this new link explicitly, as explained in Explicit Links section.

1.4.3. Explicit Links¶

You can create explicit links within your RST files. For instance, this document has a label at the top called rst_tutorial, which is specified by typing:

.. _rst_tutorial:

You can refer to this label using two different methods. The first one is:

rst_tutorial_

The second method use the ref role as follows:

:ref:`rst_tutorial`

With the first method, the link appears as rst_tutorial, whereas the second method use the first title’s name found after the link. Here, the second method would appear as Restructured Text (reST) and Sphinx CheatSheet.

Note that the second method is compulsary if the link is to be found in an external RST file. For instance, the introduction page is an external page with a link called introduction at the top of the page. You can jump there by writting :ref:`introduction`, which appears as: Introduction.

Note

Note that if you use the ref role, the final underscore is not required anymore.

1.5. List and bullets ¶

The following code:

* This is a bulleted list.
* It has two items, the second
  item uses two lines. (note the indentation)

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

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

gives:

This is a bulleted list.
It has two items, the second item uses two lines. (note the indentation)

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

Note

if two lists are separated by a blanck line only, then the two lists are not differentiated as you can see above.

1.6. Comments ¶

Comments can be made by adding two dots at the beginning of a line as follows:

.. comments

1.7. Directives ¶

Todo

explain what is a directive

1.8. Tables ¶

There are several ways to write tables. Use standard reStructuredText tables as explained here. They work fine in HTML output, however, there are some gotchas when using tables for LaTeX output.

1.8.1. Simple tables¶

Simple tables can be written as follows:

+---------+---------+-----------+
| 1       |  2      |  3        |
+---------+---------+-----------+

which gives:

Size of the cells can be adjusted as follows:

+---------------------+---------+---+
|1                    |        2| 3 |
+---------------------+---------+---+

renders as follows:

This syntax is quite limited, especially for multi cells/columns.

1.8.2. Multicells tables, first method¶

A first method is the following syntax:

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

gives:

Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4	Cells may span rows.	Cells contain blocks.

1.8.3. Multicells table, second method¶

The previous syntax can be simplified:

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

gives:

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

Note

table and latex documents are not yet compatible in sphinx, and you should therefore precede them with the a special directive (.. htmlonly::)

1.8.4. The tabularcolumns directive¶

The previous examples work fine in HTML output, however there are some gotchas when using tables in LaTeX: the column width is hard to determine correctly automatically. For this reason, the following directive exists:

.. tabularcolumns:: column spec

This directive gives a “column spec” for the next table occurring in the source file. It can have values like:

|l|l|l|

which means three left-adjusted (LaTeX syntax). By default, Sphinx uses a table layout with L for every column. This code:

.. tabularcolumns:: |l|c|p{5cm}|

+--------------+---+-----------+
|  simple text | 2 | 3         |
+--------------+---+-----------+

gives

title
simple text	2	3

1.8.5. The csv-table directive¶

Finally, a convenient way to create table is the usage of CSV-like syntax:

.. csv-table:: a title
   :header: "name", "firstname", "age"
   :widths: 20, 20, 10

   "Smith", "John", 40
   "Smith", "John, Junior", 20

a title
name	firstname	age
Smith	John	40
Smith	John, Junior	20

1.9. Include other RST files with the toctree directive ¶

Sooner or later you will want to structure your project documentation by having several RST files. The toctree directive allows you to insert other files within a RST file. The reason to use this directive is that RST does not have facilities to interconnect several documents, or split documents into multiple output files. The toctree directive looks like

.. toctree::
    :maxdepth: 2
    :numbered:
    :titlesonly:
    :glob:
    :hidden:

    intro.rst
    chapter1.rst
    chapter2.rst

Extension are optional. Here are a few notes about the different options

maxdepth is used to indicates the depth of the tree.
numbered add relevant section numbers.
titlesonly add only the main title of each document
glob can be used to glob specific patterns
hidden hides the toctree. Could be useful to indicate the hierarchy to sphinx without including the links.

The glob option works as follows:

.. toctree::
    :glob:

    intro*
    recipe/*
    *

Note also that the title that appear in the toctree are the file’s title. You may want to change this behaviour by changing the toctree as follows:

.. toctree::
    :glob:

    Chapter1 description <chapter1>

So that the title of this section is more meaningful.

1.10. Substitutions ¶

Substitutions are defined as follows:

.. _Python: http://www.python.org/

and to refer to it, use the same syntax as for the internal links: just insert the alias in the text (e.g., Python_, which appears as Python ).

A second method is as follows:

.. |longtext| replace:: this is a very very long text to include

and then insert |longtext| wherever required (e.g. here this is a longish text to include within a table and which is longer than the width of the column.).

1.11. Colored boxes: note, seealso, todo and warnings ¶

There are simple directives like seealso that creates nice colored boxes:

1.12. Inserting code and Literal blocks ¶

1.12.1. How to include simple code¶

Literal code blocks are introduced by ending a paragraph with the special marker (double coulumn) ::. The literal block must be indented. This code

This is a simple example:
import math
print 'import done'

is equivalent to this one:

This is a simple example:
::

    import math
    print 'import done'

They both create the following output:

This is a simple example:

import math
print 'import done'

1.12.2. code-block¶

By default the syntax of the language is Python, but you can specify the language using the code-block directive as follows:

.. code-block:: html
   :linenos:

   <h1>code block example</h1>

produces

1	<h1>code block example</h1>

Remove the :lineos: option to avoid numbering of the code.

1.12.3. Include code with the literalinclude directive¶

Then, it is also possible to include the contents of a file as follows:

.. literalinclude:: filename
    :linenos:
    :language: python
    :lines: 1, 3-5
    :start-after: 3
    :end-before: 5

1.13. Maths and Equations with LaTeX ¶

In order to include equations or simple Latex code in the text (e.g., $\alpha \leq \beta$ ) use the following code:

:math:`\alpha > \beta`

Warning

The math markup can be used within RST files (to be parsed by Sphinx) but within your python’s docstring, the slashes need to be escaped ! :math:`\alpha` should therefore be written :math:`\\alpha` or put an “r” before the docstring

Note also, that you can include more complex mathematical expressions using the math directive:

.. math::

    n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k

$n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k$

It seems that there is no limitations to LaTeX usage:

$s_k^{\mathrm{column}} = \prod_{j=0}^{k-1} d_j , \quad s_k^{\mathrm{row}} = \prod_{j=k+1}^{N-1} d_j .$

1.14. Auto-document your python code ¶

Let us suppose you have a python file called test.py with a function called square. The function’s code is :

def square(a):
    """short description of the function square

    longish explanation: returns the square of a: :math:`a^2`

    :param a: an input argument

    :returns: a*a
    """
    return a*a

Using the autofunction :

.. currentmodule:: test
.. autofunction:: square

Gives

square(a)¶

short description of the function square

longish explanation: returns the square of a: $a^2$

Parameters:	a – an input argument
Returns:	a*a

Here, we need to specify in which module should be found the function square, hence the .. module::test directive. You can use autoclass and automodule in the same way.

Using the module directive also creates an index (see top right of this page) so it is worth specifying mode information using platform and synopsis options:

.. module:: test
    :platform: Unix, Windows
    :synopsis: sample of documented python code

The rendering is:

Platforms: Unix, Windows

Note

the directive module should be use only once for a given module.

Warning

the python code must be in the PYTHONPATH.

1.15. Include Images ¶

Use:

.. image:: stars.jpg
    :width: 200px
    :align: center
    :height: 100px
    :alt: alternate text

to put an image

1.16. Include a Figure ¶

.. figure:: stars.jpg
    :width: 200px
    :align: center
    :height: 100px
    :alt: alternate text
    :figclass: align-center

    figure are like images but with a caption

    and whatever else youwish to add

    .. code-block:: python

        import image

gives

figure are like images but with a caption

and whatever else youwish to add

import image

1.17. Topic directive ¶

A Topic directive allows to write a title and a text together within a box similarly to the note directive.

This code:

.. topic:: Your Topic Title

    Subsequent indented lines comprise
    the body of the topic, and are
    interpreted as body elements.

gives

Your Topic Title

Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.

1.19. Other directives:: glossary, centered, index, download and field list ¶

1.19.1. Field list¶

Whatever:	this is handy to create new field and the following text is indented

using the following code:

:Whatever: this is handy to create new field

1.19.2. glossary¶

You can create glossary using

.. glossary::
     apical
        at the top of the plant.

The result looks like:

apical: at the top of the plant.

1.19.3. index¶

.. index::

Todo

explanation and example

1.19.4. download¶

You can create a link to download a file using

:download:`download test.py <test.py>`

gives download test.py

1.19.5. hlist directive¶

Bullets on several columns can be used with the hlist:

.. hlist:: ¶

.. hlist::
    :columns: 3

    * first item
    * second item
    * 3d item
    * 4th item
    * 5th item

first item
second item

3d item
4th item

5th item

1.20. Footnote ¶

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

Some text that requires a footnote [#f1]_ .

.. rubric:: Footnotes

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

You can also explicitly number the footnotes ([1]_) or use auto-numbered footnotes without names ([#]_). Here is an example [1].

1.21. Citations ¶

Citation references, like [CIT2002] may be defined at the bottom of the page:

.. [CIT2002] A citation
          (as often used in journals).

and called as follows:

[CIT2002]_

1.22. More about aliases ¶

Directives can be used within aliases:

.. |logo| image:: stars.jpg
    :width: 20pt
    :height: 20pt

Using this image alias, you can insert it easily in the text |logo|, like this logo . This is especially useful when dealing with complicated code. For instance, in order to include 2 images within a table do as follows:

+---------+---------+-----------+
| |logo|  | |logo|  | |longtext||
+---------+---------+-----------+

this is a longish text to include within a table and which is longer than the width of the column.

Note

Not easy to get exactly what you want though.

1.23. Intersphinx ¶

When you create a project, Sphinx generates a file containing an index to all the possible links (title, classes, functions, ...).

You can refer to those index only if Sphinx knowns where to find this index. THis is possible thanks to the intersphinx option in your configuration file.

For instance, Python provides such a file, by default Sphinx knows about it. The following code can be found at the end of a typical Sphinx configuration file. Complete it to your needds:

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'http://docs.python.org/': None, }

1.24. file-wide metadata ¶

when using the following syntax:

:fieldname: some contents

some special keywords are recognised. For instance, orphan, nocomments, tocdepth.

1.24.1. orphan¶

Sometimes, you have an rst file, that is not included in any rst files (when using include for instance). Yet, there are warnings. If you want to supprresse the warnings, include this code in the file:

:orphan:

There is also tocdepth and nocomments metadata. See Sphinx homepage.

1.25. metainformation ¶

.. sectionauthor:: name <email>¶

Specifies the author of the current section.:

.. sectionauthor:: John Smith <js@python.org>

By default, this markup isn’t reflected in the output in any way, but you can set the configuration value show_authors to True to make them produce a paragraph in the output.

1.26. contents directives ¶

.. contents:: ¶

.. contents:: a title for the contents
    :depth: 2

depth indicates the max section depth to be shown in the contents

Footnotes

[1]	this is a footnote aimed at illustrating the footnote capability.

Bibliography

[CIT2002]

A citation (as often used in journals).

Python string	Typical result
r"""\escape \`with` "\\""""	escape `with` "\"
"""\\escape \\`with` "\\\\""""	escape `with` "\"
"""\escape \`with` "\\""""	`escape with ""`

1.4.1. External links¶

1.4.2. Implicit Links to Titles¶

1.4.3. Explicit Links¶

1.8.1. Simple tables¶

1.8.2. Multicells tables, first method¶

1.8.3. Multicells table, second method¶

1.8.4. The tabularcolumns directive¶

1.8.5. The csv-table directive¶

1.12.1. How to include simple code¶

1.12.2. code-block¶

1.12.3. Include code with the literalinclude directive¶

1.19.1. Field list¶

1.19.2. glossary¶

1.19.3. index¶

1.19.4. download¶

1.19.5. hlist directive¶

1.24.1. orphan¶

Table Of Contents, Home

Search