.. include:: /include/substitutions.txt .. include:: /include/external_links.txt .. include:: /include/custom_roles.txt .. _implicit markup: *************** Implicit Markup *************** .. _implicit plain definition lists: Plain Definition Lists ********************** Plain Definition Lists are formatted like this in the ``.rst`` source: .. code-block:: rst 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 ``
`` elements are "simple" (i.e. do not have any sub-structures), then Sphinx additionally adorns the ``
`` element with class ``simple``. Interestingly, most ``simple``-class Definition Lists (i.e. ``
...
``) 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 (``
`` element) and the subsequent list as a single DEFINITION (``
`` element) containing a list. .. code-block:: rst - Embedded Smart Displays - `IOT_AIOT Smart Display `_ - `Uart Smart Display `_ - `HDMI Display_Raspberry Pi Display `_ - Arduino Display Results in: - Embedded Smart Displays - `IOT_AIOT Smart Display `_ - `Uart Smart Display `_ - `HDMI Display_Raspberry Pi Display `_ - Arduino Display Whereas the correct formatting looks like this: .. code-block:: rst - Embedded Smart Displays - `IOT_AIOT Smart Display `_ - `Uart Smart Display `_ - `HDMI Display_Raspberry Pi Display `_ - Arduino Display which results in: - Embedded Smart Displays - `IOT_AIOT Smart Display `_ - `Uart Smart Display `_ - `HDMI Display_Raspberry Pi Display `_ - Arduino Display 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 ``
    `` element. .. _implicit field lists: 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: .. code-block:: rst :term1: words of definition 1 :term2: words of definition 2 :longer term3: words of definition 3 or .. code-block:: rst :term1: words of definition 1 :term2: words of definition 2 :longer term3: words of definition 3 or .. code-block:: rst :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 .. _implicit option lists: 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: .. code-block:: rst -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 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 Angle brackets are also required if an option expects more than one argument.