Table Of Contents

Previous topic

1.5.1. Quick Start

Next topic

1.5.3. How to document your docstrings

This Page

1.5.2. Restructured Text (reST) and Sphinx CheatSheet

This section is a summary of the restructured Text and Sphinx syntaxes.

See also

This documentaiton is based based upon documentation found in the Sphinx and Docutils documentations.

Warning

Sphinx code is written in reST. Nonetheless, sphinx adds many additional directives on top of the reST syntax. Therefore sphinx code may not be fully compatible with reST.

1.5.2.1. Introduction

reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents.

Warning

like Python, reST syntax is sensitive to indentation !

Warning

reST requires blank lines between paragraphs

1.5.2.2. Text syntax

1.5.2.2.1. bold, italic, ...

  • one asterisk to emphasize text in italic:

    *italic*
  • and two asterisks to make it bold:

    **bold**
  • double backquotes are used to make a text verbatim. For instance, it you want to use special characters such as *:

    This ``*`` character is not interpreted
  • Finally, the single backquote is used for reST special commands (e.g., hyper links with spaces):

    This is how to create hyperlinks (see later)  `OpenAlea wiki <openalea.gforge.inria.fr>`_

Note

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:

  • 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

Warning

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:
Python string Typical result
r"""\*escape* \`with` "\\"""" *escape* `with` "\"
"""\\*escape* \\`with` "\\\\"""" *escape* `with` "\"
"""\*escape* \`with` "\\"""" escape with ""

1.5.2.2.2. Headings

Writing heading works as follows:

*****
Title
*****

subtitle
########

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

Two rules:

  • use at least as many characters as the length of the title
  • characters usage is quite flexible but be consistent

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, this convention is used which you may want to follow :

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

1.5.2.2.4. comments

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

.. comments

1.5.2.2.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)
  1. This is a numbered list.
  2. It has two items too.
  3. This is a numbered list. (buggy by the way since it should restart at 1)
  4. It has two items too.

1.5.2.2.6. tables

1.5.2.2.6.1. grid tables

simple table can be written as follows:

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

which gives:

1 2 3

A more complex example:

+------------+------------+-----------+
| 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

1.5.2.2.6.2. Simple table

=====  =====  ======
   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

1.5.2.2.6.3. Latex and special directives

Special directive or pure Latex code may be used. See Tables section in Directives.

1.5.2.3. Directives

1.5.2.3.1. Generalities

reST is mainly based on directives that are defined as follows:

.. <name>:: <arguments>
    :<option>: <option values>

    content

Example:

.. image:: ../images/test.png
    :width: 200pt

Warning

note the space between the directive and its argument as well as the blank line between the option and the content

There are many directives which are extended thanks to plugin (e.g., math plugin for latex equations).

1.5.2.3.2. Tables

Use standard reStructuredText tables as explained earlier. They 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:

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.

simple text 2 3

1.5.2.3.3. colored boxes

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

See also

This is a simple seealso note.

This is done with the following code:

.. seealso:: This is a simple **seealso** note. Other inline directive may be included (e.g., math :math:`\alpha`)

You have also the note and warning directives:

Note

This is a note box.

Warning

note the space between the directive and the text

There is another nice dircective with the todo one but it requires to add sphinx.ext.todo extension in the conf.py file and these two lines of code:

[extensions]
todo_include_todos=True

1.5.2.3.4. Code and Literal blocks

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

The two following codes:

This is a simple example::

    import math
    print 'import done'

and:

This is a simple example:
::

    import math
    print 'import done'

gives:

This is a very simple example:

import math
print 'import done'

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

   <h1>code block example</h1>

produces

<h1>code block example</h1>

1.5.2.3.5. 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.5.2.3.7. Image directive

Use:

.. image:: ../images/wiki_logo_openalea.png

to put an image

../../_images/wiki_logo_openalea.png

Note

As mentionned earlier, a directive may have options put between two columns:

.. image:: ../images/wiki_logo_openalea.png
    :width: 200px
    :align: center

1.5.2.3.8. others

Todo

glossary, centered, index

.. glossary::
.. centered::
.. index::

1.5.2.3.8.1. download

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

gives

download test.py

1.5.2.6. How to structure your reST files

1.5.2.6.1. How to include reST file using a TOC tree

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::
    :maxdepth: 2

    intro
    chapter1
    chapter2

Globbing can be used by adding the glob option:

.. toctree::
    :glob:

    intro*
    recipe/*
    *

The name of the file is used to create the title in the TOC. You may want to change this behaviour by changing the toctree as follows:

.. toctree::
    :glob:

    intro
    Chapter1 description <chapter1>

1.5.2.7. Others

1.5.2.7.1. Maths and Equations with LaTeX

Sphinx adds several extension to restructuredText among which the math extension, which allows to add Latex expressions in the text.

Note

if it does not compile, check that you have the extension [‘sphinx.ext.pngmath’] inside the file conf.py.

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 reST 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 easily more complex mathematical expressions using the math directive as follows:

.. 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.5.2.7.2. Cross-referencing syntax

Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write :role:`target`, and a link will be created to the item named target of the type indicated by role. The links’s text will be the same as target.

You may supply an explicit title and reference target, like in reST direct hyperlinks: :role:`title <target>` will refer to target, but the link text will be title.

Note

instead of :role:, you can use :ref:

1.5.2.7.3. How to add raw html

Todo

need a special plugin ?

column 1 column 1

Footnotes

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

Bibliography

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