ReST – reStructuredText

A simple markup language for plain text files.

Structural elements

Emacs ReST mode

C-c C-= Adjust/rotate or promote/demote the decorations
C-- C-c C-= reverse Adjust
C-c C-a C-d Display the title decoration hierarchy.
C-- C-c C-r <tab> shift region left
C-c C-r <tab> shift region right
C-c C-t C-t display a table of content to navigate buffer

Sectioning

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.

A = with overlines is very often preferred to a * with overlines for chapters. The previously quoted Python development guide while advising to use stars uses internally equal character.

Docutils documentation uses overlined = for parts, overlined - for chapters, = for sections, - for subsections, back quotes (`) for subsubsections.

Transition

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
Asterisk \* Asterisk *
back-quote \` back-quote `
**mark**\ up. markup.

See inline markup reference.

ReStructuredText Text Roles.

The ReStructuredText Interpreted Text Roles are valid both for reST and Sphinx processing. They are: :emphasis:, :strong:, :literal:, :code:, :math:, :pep-reference:, :rfc-reference:, :subscript:, :superscript:, :title-reference:, :raw:. The first three are seldom used because we prefer the shortcuts provided by previous reST inline markup.

The Custom Interpreted Text Roles which is a reST directive role, the tailor the renderer to apply some special formatting. We use it in Sphinx section to use a special css class for some span of text.

Lists

Bullet list

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

  * We can have subitems
  * separated by a blank line
  * and indented.

- Second item
  • First item with some lengthy text wrapping hopefully across several lines.
    • We can have subitems
    • separated by a blank line
    • and indented.
  • Second item

We can begin each item with *, +, -, •, ‣, or ⁃ followed by at least one space, you should keep the indentation of the text of the first line in subsequents lines.

See bullet list reference

Horizontal lists

.. hlist::
   :columns: 3

   * list of
   * short items
   * that should be
   * displayed
   * horizontally
  • list of
  • short items
  • that should be
  • displayed
  • horizontally

hlist is a sphinx extension, not a ReST directive

Enumerated list

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

a) Point a

   i) first subitem
   ii) second subitem

b) Point b
#) Automatic point c.
  1. We start with point number 2
  2. Automatically numbered item.
  1. Point a
    1. first subitem
    2. second subitem
  2. Point b
  3. Automatic point c.

We can use enumerate with numerals, alphabetic lower case or upper case, roman numerals lower case or upper case.

We can write enumeration followed by a period, a right parenthese, or surrounded by a parentheses; but these punctuation are not kept in the rendering; rst2html render i., i) or (i) as “i.” and Sphinx render them as “a.”.

A list must be separated from previous paragraph by a blank line, in the same way sublists must be separated from items of upper list by a blank line.

Any break of sequence in the source, produces a new list.

See enumerated list reference.

Definition list

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

how
  Definition of "how".

why :
  We define "why" we do it.

  In many paragraphs
what
Definition of “what”. We add a few words to show the line wrapping.
how
Definition of “how”.
why : cause

We define “why” we do it.

In many paragraphs.

With ReST but not Sphinx you can use a classifier after the main term like

why : cause
  We define "why" we do it.

We may have to escape a markup character to clear ambiguity between a definition list and an other construct like:

\(w)
   This is a definition list, not an enumeration.

See definition list reference.

Field list

:Name: Isaac Newton
:Long: Here we insert more text
   in many lines.
:Remark:
  Starts on the next line.
Name:Isaac Newton
Long:Here we insert more text in many lines.
Remark:Starts on the next line.

See field list reference.

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
--option-name-is-long
   description on the next line.
-v An option
-o file Same with value
--delta A long option
--delta=len Same with value
--option-name-is-long
 description on the next line.

It is nice to align option descriptions, but not mandatory, but at least two spaces must separate an option from the description.

Blocks

Literal Block

rest literal blocks

A block which is not interpreted at all is preceded by a paragraph consisting of :: and a blank line. The block must be indented.

The double :: is removed from the output.

To use a specific formatting, you can use the code directive

Block one

::

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

Block one

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

You can also put the :: at the end of the paragraph preceding the block. When text immediately precedes the :: the two colons are displayed as “:”, if there is a space before the colons they are removed from the output.

Block in condensed syntax::

  -  I'm not a list.

Block in condensed syntax:

-  I'm not a list.

Another block! ::

   In the text body,
      indentation is
   preserved

Another block!

In the text body,
   indentation is
preserved

Warning

Sphinx use literal blocks to highlight source code, so **No** is still written with a bold font by Sphinx while being not interpreted by rst2html.

To disable Pygment decorations in Sphinx use a code block in text language.

Line blocks

In a line block (ref) 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
Line block
New line and we are still on the same line
Yet a new line

Block quote

created by ... surrounding paragraph.

   Neither from itself nor from another,
   Nor from both,
   Nor without a cause,
   Does anything whatever, anywhere arise.

   --Nagarjuna - *Mulamadhyamakakarika*

Block quotes (ref) are created by just indenting them more than the surrounding paragraphs.

Neither from itself nor from another, Nor from both, Nor without a cause, Does anything whatever, anywhere arise.

—Nagarjuna - Mulamadhyamakakarika

An optional attribution can be set by a line beginning by two or three minus signs flushed left at the level of the quote.

Pull-quote

Pull-quotes (ref) are similar to blockquotes but are directives

.. pull-quote::

   Just as a solid ...
Just as a solid rock is not shaken by the storm, even so the wise are not affected by praise or blame.

Epigraph and highlights

An epigraph directive (ref) and an highlights directive (ref) are aimed to put a quotation in a distinct font.

don’t forget the final s of highlights, or you fall down on the Sphinx code highlighting directive

.. highlights::

   With these *highlights* ...
With these highlights we have completed the ReST blocks.

These three directives are similar in html rendering to Block quote but with a class of pull-quote, highlights or epigraph that your css may use but default css does not!

Container

.. container:: myclass

   There is also a general ...

There is also a general container directive whose unique effect is adding some class name to the block that your css may use. In html this paragraph is enclosed in a

<div class="myclass container">  ... </div>

Class

.. class:: myclass

The class directive ....
class reST.myclass

The class directive (ref) add a class on its content or on the first immediately following non-comment element. The name of the class is normalized by docutil to conform to the regexp: [a-z](-?[a-z0-9]+)*.

Note

While the docutil tool rst2html put as expected the previous paragraph in a:

<p class="myclass">....</p>

Sphinx shadows the class directive, so the previous code will not have the expected result. In Sphinx you have to replace class by rst-class.

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

Simple tables (ref) 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

Simple table cells are treated like a small document on their own up to line breaks, but the first column must contain a single line. e.g:

  1. Hallo
blah blah blah blah blah blah blah
blah blah
  1. Here
 We can wrap the text in source
  1. 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 (ref) have a more difficult syntax but can express more complex tables.

Header Header with 2 cols
A
Lists:
  • aha
  • yes
  1. hi
 C

B:

*hey*
a block of text
a break

You can edit them under emacs with table.el (but be careful about conflicts with rst-mode) or use org tables with orgtbl-mode and export to table with org-table-convert or org-table-create-with-table.el ( bound to C-c ~ in org-mode, but not in orgtbl-mode)

csv table.

Code

.. csv-table:: Balance Sheet
   :header: Description,In,Out,Balance
   :widths: 20, 10, 10, 10
   :stub-columns: 1

   Travel,,230.00,-230.00
   Fees,,400.00,-630.00
   Grant,700.00,,70.00
   Train Fare,,70.00,**0.00**
Balance Sheet
Description In Out Balance
Travel   230.00 -230.00
Fees   400.00 -630.00
Grant 700.00   70.00
Train Fare   70.00 0.00

The options are explained in the reference: rst directive: csv-table

You can choose a delimiter with :delim: and source an external file with the option :file:/path/of/the/file.

List Table.

A list-table (ref) is a two level list, where the first level is a row and the second one a column list. The number of column must be uniform (no column span) but cell may contain structured markup.

.. list-table:: Weather forecast
   :header-rows: 1
   :widths: 7 7 7 7 60
   :stub-columns: 1

   *  -  Day
      -  Min Temp
      -  Max Temp
      -
      -  Summary
   *  -  Monday
      -  11C
      -  22C
      -  .. image:: _static/sunny.svg
            :width: 30
      -  A clear day with lots of sunshine.
         However, the strong breeze will bring
         down the temperatures.
   *  -  Tuesday
      -  9C
      -  10C
   ...
Weather forecast
Day Min Temp Max Temp   Summary
Monday 11C 22C _images/sunny.svg A clear day with lots of sunshine. However, the strong breeze will bring down the temperatures.
Tuesday 9C 10C _images/cloudy.svg Cloudy with rain, across many northern regions. Clear spells across most of Scotland and Northern Ireland, but rain reaching the far northwest.

LaTeX table rendering.

Rendering with tabulary.

Sphinx use the latex package tabulary to render tables in laTeX.

Tabulary is an extension of the tabular package which calculate the width of columns; it has four new formats specifications: LRCJ for Left (Right, Centered, Justified) column with automatic width.

Sphinx uses by default L, but you can override it with a directive like:

.. tabularcolumns:: |L|C|C|R|

As examples in this document the source code directives table which has a proper Sphinx automatic rendering in tabulary |L|L|, which adapt the column size with a wider left one.

The two first simple tables the csv table and the list table are also rendered in tabulary with a proper calculation of table width by latex.

Rendering with tabular.

Tables that contain any kind of lists, such as object descriptions, blockquotes, or literal blocks are set by default with the tabular. In sphinx prior version 1.6 the :column: option for list table is not used for latex, and all columns are of the same size.

You can tailor the rendering by giving tabularcolumns directive which uses the p{width} column type.

Like this for three uneven columns:

.. tabularcolumns::
      |p{0.10\linewidth}|p{0.10\linewidth}|p{0.30\linewidth}|

Cross reference.

Internal document reference.

To define label as label also called explicit hyperlink target for any text location internal to a document, precede the text location with:

.. _label:
.. _other label:

plus a blank line.

A :name: option in any block is also an internal reference target.

You can also use inline internal targets

which are a _`span of running text` in a paragraph.

The ReST way of referencing a label or hyperlink targets is:

label_ or `other label`_

Reference in citation style.

A link to `Sphinx Home`_ in citation style.

.. _Sphinx Home: http://sphinx.pocoo.org

A link to Sphinx Home in citation style ( ref).

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

The reference target is composed of words made of alphabetic and numeric characters and characters in the set [,:_+-] without double hyphens, separated by spaces. (ref)

The references are equivalents when they differ only by case or number of spaces. The space character class include spaces, horizontal or vertical tabs, newlines, carriage returns, or form feeds.

When the reference has no embedded spaces the backquotes are not necessary:

A link to Sphinx_ in citation style.

If you want to use a styled reference you have to use a ref:replacement.

Embedded URI and Aliases

Reference: ref

You can directly embed an URI, a link target or an internal label in a reference enclosed in <, > in the reference.

In the same way than explicit Indirect Hyperlink. when we use a target defined elsewhere we have use a trailing underscore.

In the last example we use the label internal which is placed before the following section.

In-line versions is `Sphinx Home
<http://sphinx.pocoo.org>`_
In-line versions is Sphinx Home. 
.. _devguide:
   http://docs.python.org/devguide/

`Python development <devguide_>`_
Python development 
`Sphinx main page <Sphinx Home_>`_
Sphinx main page 
`Internal target <internal_>`_
Internal target

Difference between ReST and Sphinx location reference

Sphinx has its own preferred syntax, it uses:

:ref:`displayed text <label>`

it is specific to Sphinx and you find it in the Sphinx section.

While ReST internal hyperlinks reference a target in the same document, Sphinx allow linking across files of the same project.

These two syntax do not have the same rendering, the text of the target label is used by ReST as default displayed text, while Sphinx syntax either need a reference displayed text or when the target is preceding a section the name of the section is used as default displayed text, the text of the label is never used by Sphinx to display the link.

In this document there is two reference targets before the section Sidebar and Topic, the next table show how they are rendered.

`Sidebar`_ versus `Topic`_
Sidebar versus Topic 
:ref:`Sidebar` versus :ref:`Topic`
Sidebar and Topic versus Sidebar and Topic

You cannot use the Sphinx :ref: syntax to reference implicit hyperlink targets. but there is an autosectionlabel extension which provides a label for each section across the whole project.

When using the Sphinx syntax it is easier to always define an explicit target, which is also is more robust as a rewording of a section title will not invalidate the document.

Explicit Markup

They all begin with two periods and a white space.

Footnote

ref: footnotes

To define a footnote numbered 2 you write it .. [2] precedes the definition of the footnote 2. It is referenced by [2]_. E.g.

In the text [2]_.

.. [2] In the footnote.

In the text [2].

[2]In the footnote.
 
First automatic [#]_.
Another automatic [#]_.

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

First automatic [1]. Another automatic [3].

[1]The first automatic.
[3]The other automatic.
 
A labeled automatic [#one]_.
Another of these [#two]_.

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

A labeled automatic [4]. Another of these [5].

[4]footnote.
[5]labeled footnotes.
 
An autosymbol [*]_.
More autosymbol [*]_.

.. rubric:: Footnotes

.. [*] Footnote in a *Footnotes*
   ``rubric`` at end of document.
.. [*] other labeled footnote.

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

Footnotes

[*]Footnote in a Footnotes rubric at end of document.
[†]other labeled footnote.

Labeled footnotes are always numerics.

Citation

ref: citations and citation references

Citations are identical to footnotes except that they use only non-numeric labels.

More details are given in [project]_.

.. [project] This project began by ....

More details are given in [project].

[project]This project began by ….
 
We can use also links like Project_
As citation define ordinary target reference
We can use also links like Project

.. [project] is followed by the definition of the citation It is referenced as [project]__.

Citation labels are single word reference name.

In Sphinx, definition and reference can reside in different files.

Rest 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›

The reST directives are detailed in the docutils reference: reStructuredText Directives

We have yet see above the directives Pull-quote and Epigraph and highlights.

table of contents

Create a table of contents containing (sub)titles ranging from level 1 to level ‹number› if you use the :local: option the TOC is local to the section where it appears, otherwise it is for the whole file, the title may be empty:

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

image and figure

Images (ref) are simple pictures, see also images in the Sphinx documentation

.. image:: _static/NeoHittiteSphinx.svg
   :width: 120px
   :alt: Sphinx Neo-Hittite
   :target: https://it.wikipedia.org/wiki/Telepinu_(divinità)
Sphinx Hittite

You can click on this image to go to the target Wikipedia (it): Telepinu.

A figure (ref) add to an image an optional caption and an optional legend.

.. figure:: _static/NeoHittiteSphinx.svg
    :width: 120px
    :alt: Sphinx Neo-Hittite

    Sphinx Neo-Hittite

    Telepinu is an `Hitite <http://en.wikipedia.org/wiki/Hittites>`_
    deity.

Other options are:

  • :scale: <integer percentage>,
  • :align: {top|middle|bottom|left|right}

Images and LaTeX export

The reST command rst2latex use the width an hight of images and figures but the Sphinx laTeX exporter use also \includegraphics to import the figure; but (as a far as Sphinx 1.2pre) it does not use the width and height attribute.

To get proper figure size in latex generated by Sphinx you may have either to

  • resize the figure before including it,

  • use the :scale: option that is supported and generates a latex \scalebox

  • or put a distinct laTeX code in an raw:: latex directive that use something like:

    \includegraphics[width=60mm, height=40mm]{myfig.png}

Latex does not support svg and it has to be converted to eps or pdf, pdf being the only one to support transparency. The conversion can be done with Inkscape, it can be automated as explained by Johan B. C. Engelen. You can also use the ipe drawing editor.

Code blocks

ref: code directive

.. code:: ‹language›
   :linenos:

   ‹body›

is the ReST directive which is called in python Code highlighting. or sourcecode.

You must use code-block or sourcecode with Sphinx and the code with ReST utilities.

ReST use the same code highlighting than Sphinx, look at Sphinx code highlighting to learn about the ways to specify it.

Replacement

ReST references: replace directive, unicode directive, date directive, substitution definitions (specification), substitution definition (definition files), Character Entity Sets.

See also: docutil FAQ: How can I represent esoteric characters?.

General replacements:

This example is |stupid|

.. |stupid| replace:: not so clever
This example is not so clever

One use of replacements is to create styled reference.

If we are not satisfied by a reference like: more in ReST directives manual that you get with

.. _ more in ReST directives manual:
     http://docutils.sourceforge.net/doc...

but you want to get: more in reST directives manual.

You use the replacement:

... want to get: |more-doc|_.

.. |more-doc| replace::  *more in* **reST** *directives manual*
.. _more-doc: http://docutils.sourceforge.net/doc...

We also use substitutions to include unicode characters like © with:

.. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN

If you use Sphinx there are also three predefined substitutions: |release|, |version|, |today|.

File include

To include a ReST file use:

.. include:: subdir/incl.rst

You can put the file wherever you want the relative paths are interpreted relative to the source directory.

The options: start-line, end-line, start-after, end-before as referenced in reST Directives.

If you use include with Sphinx, you should exclude the included files from the source file lookup, by setting in conf.py the value exclude_patterns <config.html#confval-exclude_patterns> to a glob pattern in like:

exclude_patterns = ["include/**"]

For including source code in Sphinx rather use the Sphinx directive literalinclude.

Rubric

A rubric is a title not appearing in the table of contents:

.. rubric:: ‹Title›

Comment

Everything starting like a directive with two periods and a space but not a valid construct is a comment. The comment consume all indented text following it. To avoid a confusion with an other constructs, you can let the first line of a block comment empty except the two periods.

When the two dots are not followed by any text, but a blank line, this is an empty comment, that will not consume a following indented block. Empty comments are used to terminate a preceding construct.

.. One line comment

..
   A longer comment example
   more comment

   Still in comment

..

   Here is a block-quote,
   not a comment anymore
Here is a block-quote, not a comment anymore

Common options

ref: Directives Common Options

The class options :class: and :name: are supported by most of the directives.

In the following topic and autre the :name: act as a reference target. Here we can refer to the following block as say-no-more.

.. topic:: The end
   :class: exceptional
   :name: say-no-more

   A final word.

The class render in html as:

<div class="exceptional topic" id="say-no-more">
<p class="topic-title first">the end</p>
<p>A final word.</p>
</div>

the end

A final word.