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.

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 :

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

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

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:

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:

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

.. comments

Aliases:

The first method is to add at end of your reST document something like:

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

Then, write your text inserting the keywrod Python_ . The final result will be as follows: Python .

A second method is as follows:

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

and then insert |longtext| wherever needed.

Note

Note that when you define the reference or alias, the underscore is before the keyword. However, when you refer to it, the underscore is at the end. The underscore after the keyword is also used for internal references, citations, aliases ...

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:

importmathprint'import done'

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>

literalinclude:

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

In order to include equations or simple Latex code in the text (e.g., ) 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:

Analysing the code above, the ‘>>>’ sign means run the command that follows.
If a command returns a value then the next line must contain the expected results otherwise
an error occurs. This is why we put the results of square root 2 above.

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

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.