Skip to content

Latest commit

 

History

History
437 lines (257 loc) · 7.88 KB

lists.rst

File metadata and controls

437 lines (257 loc) · 7.88 KB
Raw

Lists

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

Note

The configuration value :confval:`html_compact_lists` influences the display of lists!

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:

.. rst-class:: compact

  • A paragraph.

  • Another paragraph.

    A third paragraph.

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

.. rst-class:: open
  • A paragraph.
  • Another paragraph.
Definition term
  • bullet point in definition

Normal paragraph in definition.

Admonition

  • bullet point in admonition

Topic

  • bullet point in topic

Sidebar

  • bullet point in sidebar

Compact list in topic

  • A paragraph.
  • Another paragraph.

Non-compact list in topic

  • A paragraph.

  • Another paragraph.

    A third paragraph.

  • 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.

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.

  3. Arabic numerals.

    1. lower alpha)
      1. (lower roman)
        1. upper alpha.
          1. upper roman)

  4. 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

Topic

  1. enumerated list item in topic

Sidebar

  1. enumerated list item in sidebar

hlist

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

.. hlist::
    :columns: 3

    * A list of
    * short items
    * that should be
    * displayed
    * horizontally

Admonition

.. hlist::
    :columns: 3

    * ``hlist``
    * in
    * admonition

Topic

.. hlist::
    :columns: 3

    * ``hlist``
    * in
    * topic

Sidebar

.. hlist::
    :columns: 3

    * ``hlist``
    * in
    * sidebar

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 3 : classifier
Definition 3.
term 4 : classifier one : classifier two
Definition 4.
term with code and bold
Definition with code and bold.

Admonition

term with code and bold
in admonition

Topic

term with code and bold
in topic

Sidebar

term with code and bold
in sidebar

Glossary

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

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

.. glossary::

    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

.. glossary::
    term in admonition
        definition

    term in admonition with ``code`` and **bold**
        definition

link: :term:`term in admonition`

Topic

.. glossary::
    term in topic
        definition

    term in topic with ``code`` and **bold**
        definition

link: :term:`term in topic`

Sidebar

.. glossary::
    term in sidebar
        definition

    term in sidebar with ``code`` and **bold**
        definition

link: :term:`term in sidebar`

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

Topic

field:value

Sidebar

field:value

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.

Topic

--flag Description.

Sidebar

--flag Description.

Grammars

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

Example link: :token:`try_stmt`.

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