reST

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

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

a) Point a
b) Point b
#) Automatic point c.

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

Enumerated list

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

1. Point a
2. Point b
3. Automatic point c.

Note

Automatic alphabetic numbering works wrongly in Sphinx, but does work with plain rst2html.

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.

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. :ref:subversion repository URL <svnRepoURL> links to my document on subversion.

In Sphinx it is possible to reference a document as follows

:doc:`reST`

reST

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

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

.. contents:: `Table of contents`
   :depth: ‹number›

---

Include an image:

.. image:: ‹file name›

---

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.

---

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

Sphinx directives

Create a table of contents across 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 :ref: reST table of contents <reST-tableOfContents>` 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›

---

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›”.

---

A glossary is created as follows:

.. glossary::

   ‹reST definition list›

---

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.

---

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

.. sidebar:: ‹Title›

   ‹body›

---

Create a boxed note with ‹text›:

.. note:: ‹text›

Note

This is a note.

---

Create a boxed warning with ‹text›:

.. warning:: ‹text›

Warning

This is a warning.

---

Create a see also box:

.. seealso::

   ‹reST definition list›

See also

Apples

A kind of fruit.

---

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

.. rubric:: ‹Title›

---

Create a centered, boldface text block with:

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