ReST – reStructuredText

A simple markup language for plain text files.

Structural elements

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

See inline markup reference.

These inline markups are also provided by ReStructuredText Interpreted Text Roles. The roles are described in the Sphinx chapter

Lists

Bullet list

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

See bullet list reference

Horizontal lists

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

Enumerated list

  1. We start with point number 2
  2. Automatically numbered item.
  1. Point a
  2. Point b
  3. Automatic point c.

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 : cause

We define “why” we do it.

In many paragraphs.

See definition list reference.

Field list

Name:Isaac Newton
Long:Here we insert more text to show the effect of many lines.
Remark:The source 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

Blocks

Literal Block

rest literal blocks

A block which is not interpreted at all is preceded by a :: and a blank line. The block must be indented. If no white space is preceding the :: then it is displayed as ”:”.

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

Block one:

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

Another block!

In the text body,
   indentation is
preserved

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

Block quote

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

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.

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

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

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

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

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 carefull 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 tables

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 Tables

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.

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 re:source code directives table source_code_directives 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 environment with equal column size, you can taylor the rendering by giving tabularcolumns directive which uses the p{width} column type.

An example is the following source code include table which use both description and verbatim for wich the automatic Sphinx rendering in latex is:

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}

If necessary we can adapt the relative length of columns.

Cross references

internal document reference

To define label as label for any text location internal to a document, precede the text location with:

.. _label:

plus a blank line.

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

There are two ways of referencing a label.

The reST way is:

`label`_

The preferred Sphinx way, allows linking across files, it uses:

:ref:`displayed text <label>`

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

Section titles, footnotes, and citations automatically are link targets. `Transition`_ produces Transition. But you cannot use them as target of a link in the Sphinx ref syntax.

You can then also reference the Transition section as how to draw an horizontal line with the hyperlink: `how to draw an horizontal line`_ and the indirect reference:

.. _how to draw an horizontal line: Transition_

Explicit Markup

They all begin with two periods and a white space.

Footnotes (ref)

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

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

There is no labeled version of these autosymbol footnotes.

Citations

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

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

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.

Sphinx Hittite

Sphinx Hittite

Telepinu is an Hitite deity.

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

replacements

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

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

General replacements:

.. |something| replace:: here we
   define what something is.

Here |something| will be replaced by its definition.

Instead of replace you can also use image more in reST directives manual

It is the only way for nesting inline markup to create styled references like we did above.

We also use substitutions to include unicode characters like ©.

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

file includes

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 is followed by normal text is a comment. Mark the indentation in the example:

Common options

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

The following topic 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 :name: act as a reference target and allow to refer to the following block as say-no-more

the end

A final word.