reStructuredText Primer

This is a simplified version of the excellent Sphinx reStructuredText Primer. It’s meant to be viewed in the CodeChat System, which displays the source text and the resulting rendered HTML side by side.

Inline markup

The standard reST inline markup is quite simple: emphasis (italics), strong emphasis (boldface), and code samples.

Lists and Quote-like blocks

  • This is a bulleted list.

  • It has two items, the second item uses two lines.

  1. This is a numbered list.

  2. It has two items too.

reST can autonumber lists:

  1. This is a numbered list.

  2. It has two items too.

    Quoted paragraphs are created by just indenting them more than the surrounding paragraphs.

Line blocks are a way of preserving line breaks:

These lines are
broken exactly like in
the source file.

Source Code

Literal code blocks are introduced by ending a paragraph with the special marker:

void foo(int bar) {
   return bar
}

Tables

Two forms of tables are supported: Grid tables like this:

Header row, column 1 (header rows optional)

Header 2

Header 3

Header 4

body row 1, column 1

column 2

column 3

column 4

body row 2

…and simple tables like this:

A

B

A and B

False

False

False

True

False

False

False

True

False

True

True

True

Sections

Section headers are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text.

Images

reST supports an image directive:

../_images/gnu.png

Gotchas

There are some problems one commonly runs into while authoring reST documents:

  • Separation of inline markup: Inline markup spans must be separated from the surrounding text by non-word characters; you have to use a backslash-escaped space to get around that. For example, use H\ :sub:`2`\ O (H2O), not H:sub:`2`O (which produces as error).

  • No nested inline markup: Something like H:sub:`2`O is not possible.