# 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

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

### Horizontal lists¶

 list of short items that should be displayed horizontally

### Enumerated list¶

2. Automatically numbered item.
1. Point a
2. Point b
3. Automatic point c.

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

### Field list¶

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

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:

 Hallo blah blah blah blah blah blah blah blah blah Here We can wrap the text in source There aha

### Grid tables¶

Grid tables (ref) have a more difficult syntax but can express more complex tables.

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 A clear day with lots of sunshine. However, the strong breeze will bring down the temperatures.
Tuesday 9C 10C 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.

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

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.

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

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¶

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