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
Item 1 initial text.
Item 1a.
Item 1b.
Item 2a.
Item 2b.
Arabic numerals.
lower alpha)
(lower roman)
upper alpha.
upper roman)
Lists that don’t start at 1:
Three
Four
C
D
iii
iv
More than four
Nested lists, each item containing a single paragraph and/or a single nested list, each item containing …
Paragraph.
Paragraph.
Second level paragraph
Third level paragraph
Another third level paragraph
Another second level paragraph
Successive lists:
Paragraph.
A paragraph in a new list.
Admonition
enumerated list item in admonition
6.3 hlist
#
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-hlist
|
|
|
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.
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#
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