6 Lists#

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks

Note

The configuration value html_compact_lists influences the display of lists!

6.1 Bullet Lists#

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists

A single list item containing a single paragraph:

  • A paragraph.

A single list item containing multiple paragraphs:

  • A paragraph.

    Another paragraph.

Multiple list items containing a single paragraph each:

  • A paragraph.

  • Another paragraph.

Multiple list items, some containing multiple paragraphs:

  • A paragraph.

  • Another paragraph.

    A third paragraph.

Nested lists, each item containing a single paragraph and/or a single nested list, each item containing …

  • A paragraph.

  • Another paragraph.

    • A second level paragraph.

    • A second level paragraph with significantly more text in it. So much text that there will be at least one line break within the paragraph. This will show the difference in spacing between lines and list items. Do you see a difference? Or is it the same?

  • Another first level paragraph.

An example that doesn’t fulfill this rule (only the nested sub-list does):

  • A paragraph.

  • Another paragraph.

    • A second level paragraph

    • A second level paragraph

    Yet another paragraph.

Compact lists can be manually forced by using the compact class:

  • A paragraph.

  • Another paragraph.

    A third paragraph.

Non-compact lists can be manually forced by using the open class:

  • A paragraph.

  • Another paragraph.

Definition term
  • bullet point in definition

Normal paragraph in definition.

Admonition

  • bullet point in admonition

  • A list item containing admonitions containing further lists:

    Compact list in admonition

    • A paragraph.

    • Another paragraph.

    Non-compact list in admonition

    • A paragraph.

    • Another paragraph.

      A third paragraph.

6.2 Enumerated Lists#

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists

  1. Item 1 initial text.

    1. Item 1a.

    2. Item 1b.

    1. Item 2a.

    2. Item 2b.

  2. Arabic numerals.

    1. lower alpha)

      1. (lower roman)

        1. upper alpha.

          1. upper roman)

  3. Lists that don’t start at 1:

    1. Three

    2. Four

    1. C

    2. D

    1. iii

    2. iv

    1. More than four

Nested lists, each item containing a single paragraph and/or a single nested list, each item containing …

  1. Paragraph.

  2. Paragraph.

    1. Second level paragraph

      • Third level paragraph

      • Another third level paragraph

    2. Another second level paragraph

Successive lists:

  1. Paragraph.

  1. A paragraph in a new list.

Admonition

  1. enumerated list item in admonition

6.3 hlist#

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-hlist

  • A list of

  • short items

  • that should be

  • displayed

  • horizontally

Admonition

  • hlist

  • in

  • admonition

6.4 Definition Lists#

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists

term 1

Definition 1.

term 2

Definition 2, paragraph 1.

Definition 2, paragraph 2.

term 3classifier

Definition 3.

term 4classifier oneclassifier two

Definition 4.

term with code and bold

Definition with code and bold.

Admonition

term with code and bold

in admonition

6.5 Glossary#

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary

Example link: source directory (term will be highlighted).

environment#

A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents.

source directory#

The directory which, including its subdirectories, contains all source files for one Sphinx project.

term 1#
term 2#

Definition of both terms.

term with code and bold#

Definition with code and bold.

Admonition

term in admonition#

definition

term in admonition with code and bold#

definition

link: term in admonition

link: term in topic

link: term in sidebar

6.6 Field Lists#

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-field-lists

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists

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

Admonition

field:

value

6.7 Option Lists#

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists

-a

Output all.

-b

Output both (this description is quite long).

-c arg

Output just arg.

--long

Output all day long.

-p

This option has two paragraphs in the description. This is the first.

This is the second. Blank lines may be omitted between options (as above) or left in (as here and below).

--very-long-option

A VMS-style option. Note the adjustment for the required two spaces.

--an-even-longer-option

The description can also start on the next line.

-2, --two

This option has two variants.

-f FILE, --file=FILE

These two options are synonyms; both have arguments.

/V

A VMS/DOS-style option.

Admonition

--flag

Description.

6.8 Grammars#

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#grammar-production-displays

Example link: try_stmt.

try_stmt  ::=  try1_stmt | try2_stmt
try1_stmt ::=  "try" ":" suite
               ("except" [expression ["," target]] ":" suite)+
               ["else" ":" suite]
               ["finally" ":" suite]
try2_stmt ::=  "try" ":" suite
               "finally" ":" suite