reStructuredText and Sphinx Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.

Table of Contents

Intro

Collections

Elements

Etc.

Lists

List items indentation

Tricky part of reStructuredText is indentation. Wrongly indented means wrongly recognized.

Extreme attention has to be paid for bullet or enumerated lists. List item content needs to keep proper indentation level.

1* list item #1
2* item #2 is on three lines
3  in the source but they are
4  all the same indented
5* item #3
6* item #4 contain sublist

  • list item #1

  • item #2 is on three lines in the source but they are all the same indented

  • item #3

  • item #4 contain sublist

Sublists indentation

Another source of pain is keeping proper indentation when creating nested lists (sublists).

 1* list item #1
 2* item #2 is on three lines
 3  in the source but they are
 4  all the same indented
 5* item #3
 6* item #4 contain sublist
 7
 8  * sublist must be intended
 9    on the same level as
10    parent item
11  * also, item #4 and sublist must be
12    separated by the blank line
13
14* item #5 returns back to the
15  original indentation

  • list item #1

  • item #2 is on three lines in the source but they are all the same indented

  • item #3

  • item #4 contain sublist

    • sublist must be intended on the same level as parent item

    • also, item #4 and sublist must be separated by the blank line

  • item #5 returns back to the original indentation

Previous example also shows that block elements must be separated by the at least one blank line. If you forgot to separate sublist new a blank line, it will be a continuation of item #1:

1* item #1
2  * sublist without separating blank line is continuation of previous element
3
4* item #2
5
6  * sublist has to be started with the blank line
7
8* item #3

  • item #1 * sublist without separating blank line is continuation of previous element

  • item #2

    • sublist has to be started with the blank line

  • item #3

Another crazy situation easily occurs if you indent the sublist, but not at the same level as the parent item:

 1Wrong indented sublist:
 2
 3#. list #1
 4
 5 #. not a sublist of #1 but a block quote!
 6
 7#. another list #2, not related to the previous one
 8
 9Above fixed:
10
11#. list #1
12
13   #. sublist of #1 because it's indented as parent item
14
15#. still list #1, the second item

Wrong indented sublist:

  1. list #1

  1. not a sublist of #1 but a block quote!

  1. another list #2, not related to the previous one

Above fixed:

  1. list #1

    1. sublist of #1 because it’s indented as parent item

  2. still list #1, the second item

Previous: Inline elements | Next: Document parts

On this page