7. Implicit Markup

7.1. Plain Definition Lists

Plain Definition Lists are formatted like this in the .rst source:

term1
    words of definition 1

term2
    words of definition 2

When they are rendered, they look like this:

term1

words of definition 1

term2

words of definition 2

If all <dl> elements are “simple” (i.e. do not have any sub-structures), then Sphinx additionally adorns the <dl> element with class simple.

Interestingly, most simple-class Definition Lists (i.e. <dl class="simple">...</dl>) are unintentional and are caused by erroneous list formatting in the source file like this, where the indented part is intended to be a sub-list, but because no preceding blank line was present, is instead interpreted as a Definition List with - Embedded Smart Displays as the TERM (<dt> element) and the subsequent list as a single DEFINITION (<dd> element) containing a list.

- Embedded Smart Displays
    - `IOT_AIOT Smart Display <https://viewedisplay.com/iot_aiot-smart-display/>`_
    - `Uart Smart Display <https://viewedisplay.com/uart-smart-display/>`_
    - `HDMI Display_Raspberry Pi Display <https://viewedisplay.com/hdmi-display-raspberry-pi-display/>`_
    - Arduino Display

Results in:

Whereas the correct formatting looks like this:

- Embedded Smart Displays

  - `IOT_AIOT Smart Display <https://viewedisplay.com/iot_aiot-smart-display/>`_
  - `Uart Smart Display <https://viewedisplay.com/uart-smart-display/>`_
  - `HDMI Display_Raspberry Pi Display <https://viewedisplay.com/hdmi-display-raspberry-pi-display/>`_
  - Arduino Display

which results in:

which Sphinx then correctly interprets - Embedded Smart Displays as a list item (in a parent list) and the sub-list as a sub-list, correctly encased in a <ul> element.

7.2. Field Lists

Field Lists are formatted like this in the .rst source. They are often used for listing fields in a C struct or arguments in a function signature, but their REAL broader use is that they are usually formatted in a more compact form than plain definition lists: the “term” part (which could be any kind of list item) is positioned in its own (usually narrow) column on the left, and the “definition” part is formatted in its own column on the right, in a table format such that the left edge of the definition column is slightly to the right of the widest “term” list item.

Example source:

:term1:  words of definition 1
:term2:  words of definition 2
:longer term3:  words of definition 3

or

:term1:
    words of definition 1
:term2:
    words of definition 2
:longer term3:
    words of definition 3

or

:term1:

    words of definition 1

:term2:

    words of definition 2

:longer term3:

    words of definition 3

(The latter format can be advantageous if the definition parts are long.)

When Sphinx renders them, all of the above source formats look like this:

term1:

words of definition 1

term2:

words of definition 2

longer term3:

words of definition 3

7.3. Option Lists

Option Lists are a feature of reStructuredText and are generated by source that is literally formatted like a command-line options list. Source formatting to generate them is documented in the Option Lists Specification, part of the reStructuredText specification.

The objective is nearly identical to Field Lists: format in a compact readable form. And like Field Lists, the comma-separated list of options (that mean the same thing) are the “term” part, and the description is the “definition” part.

Example source:

-a         Output all.
-c arg     Output just arg.
--long     Output all day long.
/V         A VMS/DOS-style option.

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

-f <[path]file>  Option argument placeholders must start with
                 a letter or be wrapped in angle brackets.

-d <src dest>    Angle brackets are also required if an option
                 expects more than one argument.

When Sphinx renders them, it looks like this:

-a

Output all.

-c arg

Output just arg.

--long

Output all day long.

/V

A VMS/DOS-style option.

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

-f <[path]file>

Option argument placeholders must start with a letter or be wrapped in angle brackets.

-d <src dest>

Angle brackets are also required if an option expects more than one argument.