Lists

Please Don’t

  1. Please do not indent lists in markup. This is unnecessary — lists are automatically offset (indented) in the output. Adding indentation in the markup will over-indent the list in output.

  2. Please do not use * for lists.

  • Item 1

  • Item 2

  • Item 3

  • Item 4

Please use +, -, •, ‣, or ⁃ for lists; avoid using * (All are valid unordered list markers in reST. The last three are special characters—valid, but not easy to type. Stick with + or - as a rule.)

.. _icgsphinx-lists:

Lists
#####

.. admonition:: :flag:`Please Don't`
   :name: nolistindent
   :class: aside

   1. :ref:`Please do not indent lists in markup <dontuseasterisk>`. This is
   unnecessary — lists are automatically offset (indented) in the output.
   Adding indentation in the markup will *over*-indent the list in output.

   2. :ref:`Please do not use * for lists. <dontuseasterisk>`

+ Item 1

+ Item 2

+ Item 3

- Item 4

Please use +, -, •, ‣, or ⁃ for lists; avoid using \* (All are valid
unordered list markers in reST. The last three are special characters—valid,
but not easy to type. Stick with + or - as a rule.)

Docutils defines all list behavior; Sphinx (and ICG, for that matter) does not add to/extend any of the three principal list types provided by Docutils:

Only the first two are of concern in this topic.

Escaping the List Mechanism

  1. Not Escaped

To make the above look like an informal section, there will be indentation trouble unless the list item marker is escaped.

+ Escaped: Unordered List Marker

(2) Escaped: Ordered List Marker

Put a slash (\) in front of the marker to prevent reST from interpreting it as a list item.

(1) Not Escaped

To make the above look like an informal section, there will be indentation
trouble unless the list item marker is escaped.

\+ Escaped: Unordered List Marker

\(2) Escaped: Ordered List Marker

Put a slash (\\) in front of the marker to prevent Sphinx from interpreting
it as a list item.

When to Use an Ordered List

In short, always use unordered lists unless there is a reason to use an ordered (enumerated) list. There are three reasons to number a list:

  • the list is stated to have a certain number of items (“There are three reasons to number a list …”),

  • the items on the list will be referred to later in body text (”… in Step (4) as described above…”), or

  • the order of items is a fixed aspect of the list (the third item is never listed before the first, etc.).

One can often avoid the third case if the order of processing (top to bottom) will be sufficient to convey the expected order. For instance, it is a commonplace of narratology that stories have

  • a beginning,

  • a middle, and

  • an end.

Yes, the above list could take numbers, but they aren’t really necessary. They would not enhance the intended sense of order.

The above “rules” become more prevailing as list length increases. Either of the two lists in this section might be enumerated according to the rationales provided. However, the lists are short. Adding numbers is more superfluity than necessity. As a rule of thumb, once a list exceeds six items numbers may be advisable if one or more of the criteria above is met.

List Grammar

Punctuate a list as if the bullets weren’t there: put a comma after each element but the last, include the appropriate conjunction at the end of the penultimate item, and put a period after the last item. The two preceding lists illustrate. This usage is only excepted when a list cannot be constructed in this way, which is a rarity. In that case, omit the punctuation and the conjunction after the penultimate list item.