1.8. Lists, Definition Lists

List markup is natural: just place an asterisk or hyphen at the start of a paragraph and indent properly. The same goes for numbered list (number or letter with tailed dot); they can also be automatically numbered using a # sign.

Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines.

1.8.1. Unordered (bullet) Lists

Bullet lists contains list item elements which are uniformly marked with bullets. Bullets are typically simple dingbats (symbols) such as circles and squares.

bulleted lists ( <ul> )

the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
* This is a bulleted list ...
* ... use asterisks.
* It has fife items, the third
  item uses two lines.
* Are unindented at the first level.
* Must have a blank line before and after.

  - This is a bulleted list ...
  - ... use hyphens.
  - Are indented at the first level to stand out from the
    previous paragraph.

    - the blank line requirement means that nested list items
      will have a blank line before and after as well

    - you may *optionally* put a blank line *between* list items
which gives

  • This is a bulleted list …

  • … use asterisks.

  • It has fife items, the third item uses two lines.

  • Are unindented at the first level.

  • Must have a blank line before and after.

    • This is a bulleted list …

    • … use hyphens.

    • Are indented at the first level to stand out from the previous paragraph.

      • the blank line requirement means that nested list items will have a blank line before and after as well

      • you may optionally put a blank line between list items

1.8.2. Ordered (numbered) Lists

Enumerated lists (a.k.a. “ordered” lists) are similar to bullet lists, but use enumerators instead of bullets. An enumerator consists of an enumeration sequence member and formatting, followed by whitespace. Different enumeration sequences are possible, e.g. Arabic or Roman numerals or alphabet characters.

numbered lists ( <ol> )

the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
1. This is a numbered list.
2. Start each line with a number and period.
3. Can begin on any number.

8. Must have a blank line before and after.
9. Can have nested sub-lists.

   a. nested lists are numbered separately
   #. nested lists need a blank line before and after

#. Can have automatic number with the ``#`` character.
which gives

  1. This is a numbered list.

  2. Start each line with a number and period.

  3. Can begin on any number.

  1. Must have a blank line before and after.

  2. Can have nested sub-lists.

    1. nested lists are numbered separately

    2. nested lists need a blank line before and after

  3. Can have automatic number with the # character.

1.8.3. Definition (description) Lists

Definition Lists contains a list of terms and their definitions. Each list item element contains a term, optional classifiers, and a definition.

definition list ( <dl> )

the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
Definition list
   a list with several term-definition pairs in the form

   .. parsed-literal::

      **TERM**
         DEFINITION (*description of term*)

   Terms
      should not be indented

   Definitions
      should be indented under the term

Line spacing
   there should be a blank line between term-definition pairs
which gives
Definition list

a list with several term-definition pairs in the form

TERM
   DEFINITION (description of term)
Terms

should not be indented

Definitions

should be indented under the term

Line spacing

there should be a blank line between term-definition pairs

Field (description) Lists

Field lists are special definition lists. They may also be used for two-column table-like structures resembling database records (label & data pairs). Sphinx extends standard docutils behavior for Field Lists and intercepts field lists specified at the beginning of documents and adds some extra (optional) functionality.

field list

the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
          - I
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up
   with the first line, but they must be indented relative to the
   field name marker, and they must line up with each other.
:Parameter i: integer
which gives
Date

2001-08-16

Version

1

Authors

  • Me

  • Myself

  • I

Indentation

Since the field marker may be quite long, the second and subsequent lines of the field body do not have to line up with the first line, but they must be indented relative to the field name marker, and they must line up with each other.

Parameter i

integer