A block of text is simply a paragraph, set off from other paragraphs, by a blank line. This is the fundamental unit of the RST markup. RST recognizes a number of kinds of paragraphs, based on the pattern that is followed. Here's an example of a heading:

This Is A Heading 
================= 

This is recognized as a heading because it's underlined with a repeated string of special characters.

The docutils parser deduces the hierarchy of title underlines based entirely on their usage. We must be consistent with our headings and their nesting. It helps to pick a standard and stick to it. It also helps to keep documents fairly flat without complex, nested headings. Three levels are often all that's needed; this means that we can use ====, ----, and ~~~~ for the three levels.

A bullet list item begins with a special character; the content must also be indented. As Python uses a 4-space indent, this is common in RST as well. However, almost any consistent indent will work:

Bullet Lists 
 
-   Leading Special Character. 
 
-   Consistent Indent. 

Note the blank line between paragraphs. For some kinds of simple bullet lists, the blank lines aren't required. In general, blank lines are a good idea.

A numerical list begins with a digit or letter and a roman numeral. To have numbers generated automatically, # can be used as the list item:

Number Lists 
 
1.  Leading digit or letter. 
 
#.  Auto-numbering with #. 
 
#.  Looks like this. 

We can use the indent rules to create lists within lists. It can be complex, and the docutils RST parser will usually figure out what you meant.

A block quote is simply indented text:

Here's a paragraph with a cool quote. 
 
    Cool quotes might include a tip. 
 
Here's another paragraph. 

Code samples are indicated with a :: double colon; they are indented, and they end with a blank line. While :: can be at the end of a line or on a line by itself, putting :: on a separate line makes it slightly easier to find code samples.

Here's a code sample:

Here's an example:
:: 
 
    x = Deck() 
    first_card = x.pop() 
 
This shows two lines of code. It will be distinguished from surrounding text. 

The docutils parser will also locate the doctest material and set it aside for special formatting, similar to a code block. They begin with >>> and end with a blank line.

Here's some sample output from doctest:

Here's an example:
::
 
    >>> x = Unsorted_Deck() 
    >>> x.pop() 
    'A♣' 
 
This shows how the :class:`Unsorted_Deck` class works.

A blank line at the end of the test output is essential and is easily overlooked. When the doctest error messages include the surrounding text, this means that additional blank lines are required. 

One way in which we can annotate our text is by providing inline markup to identify things that should be emphasized in different ways. It might be code, or an important word, or a cross-reference. In the next section, we'll show how inline markup is used in RST.