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
This is a numbered list.
Start each line with a number and period.
Can begin on any number.
Must have a blank line before and after.
Can have nested sub-lists.
nested lists are numbered separately
nested lists need a blank line before and after
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