reStructuredText Primer

Author: Kushal Das
Date: 2012-07-23

Packages you need

What is it ?

reStructuredText is plaintext that uses simple and intuitive constructs to indicate the structure of a document.


Open a new file called test.rst

$ vi test.rst

We will use this file for all our examples.

Document title

Document Title Text

The above will create the title of the document with Document Title Text as title.

How to view the output ?

We can have output in various formats. For our session we will use HTML. Use the following command to create test.html and view it in the browser.

$ rst2html test.rst test.html

Whitespace & paragraphs

Spaces are recommended for indentation. Blank lines are used to separate paragraphs. Multiple blank lines will be equivalent to a single blank line.

This is first paragraph.

This is the second paragraph. This can continue in our example.


.. This is a comment
   _so: is this!
   [and] this!
   this:: too!
   |even| this:: !

Section Titles

Recomended characters to create section titles are

= - ` : . ' " ~ ^ _ * + #

Example section title

Section Title

Subsection & hierchay

Once a hierarchy of title styles is established, sections must use that hierarchy. We use this to create subsections.

Subsection Title
A paragraph for the subsection.

Re-generate the test.html file and see how it looks :)

Bullet Lists

A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed by whitespace, is a bullet list item (a.k.a. "unordered" list item).

- Item 1
- Item 2
- Item 3

Not part of list.

Ordered Lists

They are similar to bullet lists but use enumerators instead of bullets. It contains enumeration sequence member and formatting, followed by whitespace.

1. Item 1 text
2. Item 2 text

More on ordered lists

To get auto-enumeration one can use #.

1. New item 1
#. New item 2
#. New item 3

Definition list

Definition list item contains a term, optional classifiers, and a definition. A term is a simple one-line word or phrase. Optional classifiers may follow the term on the same line, each after an inline " : " (space, colon, space). A definition is a block indented relative to the term

More on Definition list


term 1
    Definition 1.

term 2
    Definition 2, paragraph 1.

term 3 : classifier
    Definition 3.

Option Lists

Option lists are two-column lists of command-line options and descriptions, documenting a program's options.

-a         Output all.
-b         Output both (this description is
           quite long).
-c arg     Output just arg.
--long     Output all day long.

Literal Blocks

Literal Blocks are the places where no markup processing is done.


    for a in [5,4,3,2,1]:   # this is program code, shown as-is
        print a
    print "it's..."
    # a literal block continues until the indentation ends

Doctest blocks

Doctest blocks are interactive Python sessions cut-and-pasted into docstrings.

Normal plain text paragraph.

>>> print 'this is a Doctest block'
this is a Doctest block

We will use this a lot while commenting the source code we will write.


We can write simple tables like

=====  =====  =======
A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Grid Tables

| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
| body row 1, column 1   | column 2   | column 3 | column 4 |
| body row 2             | Cells may span columns.          |
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |


We can use directives to create notes section.

.. note:: This is a note.

   - List item 1
   - List item 2


For emphasis in the text we use *.

This is *emphasized text*.


This is an example of auto-numbered footnote.

Please RTFM [#]_ or you can read [#]_.

.. [#] Read The Fine Manual
.. [#] The next fine manual



reStructuredText Markup Specification

Summer Training

Participate in dgplug Summer training

Thank You