reStructuredText conventions

File extension

Although .txt extension is probably technically correct for RST files, use .rst for internal documentation for better compatibility with editors, GitHub, etc.

Section markers

Book level:

1. Over- and underlined hash marks (#) for book title
2. Over- and underlined stars (*) for book sub-title

File level:

1. Over- and underlined equals signs (=) once at top of file (file topic)
2. Underlined equals signs (=)
3. Underlined minus signs (-)
4. Underlined colons (:)
5. Underlined periods (.)

The book level notation is reserved for future use. It allows the internal documentation to be easily built into a single HTML/PDF file for ease of browsing.

Page breaks

See http://comments.gmane.org/gmane.text.docutils.user/6473.

You can use:

.. raw:: LaTeX

   \newpage

Lists

Numbering

List numbering styles can be mixed, e.g.:

1. Foo

  a. Bar

     1. Quux

However, e.g. GitHub will renumber the bullets and may also change the numbering style. This will make references to list elements confusing; e.g. if you refer to Quux as element 1.a.1 above, the reference is quite confusing if Quux was renumbered to 1.1.1 or 1.a.iii. Even so, such references are sometimes necessary, so they can be used. Start at zero indent.

Bullets

Recommended bullet styles by level:

* Foo

  + Bar

    - Quux

Start at zero indent

Start lists at zero indent, e.g.:

* Foo

* Bar

If you don't, GitHub will render the list as a quoted block.

Empty lines

Use empty lines between elements and sub-elements for readability and to minimize formatting issues:

1. Foo

  a. sub-foo

     + sub-sub-foo

  b. sub-bar

2. Bar

3. Quux

Nested lists

While rst2pdf and friends are somewhat lenient with respect to nested lists, some RST formatters are a bit more picky. To work well with all formatters, make sure that a nested list's bullet mark is indented to the level of the previous level's body, e.g.:

1. Foo

   a. sub-foo

   b. sub-bar

2. Bar

The following is incorrect and may render the nested list as a quoted block:

1. Foo

  a. sub-foo

  b. sub-bar

2. Bar

Note that the required level depends on the length of the parent bullet. This matters for numbered lists:

9. Foo

   a. sub-foo

   b. sub-bar

10. Bar

    a. sub-foo (with one more indent than above)

    b. sub-bar