reStructuredText Primer

This is a simplified version of the excellent Sphinx reStructuredText Primer.

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

Hyperlinks

Use link text for inline web links. Or, refer to a label.

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:

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, H₂O, not H:sub:`2`O.

  System Message: WARNING/2 (E:\enki_all\CodeChat\docs\rest-primer.rst, line 84); backlink

  Inline interpreted text or phrase reference start-string without end-string.

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