Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

Definition lists

List style "dl-parameters"

This list style is used in TYPO3 documentation to style the explanation and description of parameters. The general markup we use is that of a "definition list".

Example 1: No Extra Styling

An example with a standard styling would look like this:

Source:

parameterAbc
    Condition: required, Type: string, Default: ''

    Text describing parameterAbc ...

parameterBcd
    Condition: optional, Type: boolean, Default: false

    Text describing parameterBcd ...

Rendering result:

parameterAbc

Condition: required, Type: string, Default: ''

Text describing parameterAbc ...

parameterBcd

Condition: optional, Type: boolean, Default: false

Text describing parameterBcd ...

This markup works but isn't very readable due to the lack of styling.

Example 2: Nicely Styled

Source:

..  rst-class:: dl-parameters

parameterAbc
    :sep:`|` :aspect:`Condition:` required
    :sep:`|` :aspect:`Type:` string
    :sep:`|` :aspect:`Default:` ''
    :sep:`|`

    Text describing parameterAbc ...

parameterBcd
    :sep:`|` :aspect:`Condition:` optional
    :sep:`|` :aspect:`Type:` boolean
    :sep:`|` :aspect:`Default:` false
    :sep:`|`

    Text describing parameterBcd ...

Rendering result:

parameterAbc

| Condition: required | Type: string | Default: '' |

Text describing parameterAbc ...

parameterBcd

| Condition: optional | Type: boolean | Default: false |

Text describing parameterBcd ...

Explanation:

Right in front of the definition list we place an 'rst-class' directive with 'dl-parameters', meaning a definition list style for parameters. As a result the rendered html construct will look like <dl class="dl-parameters">...</dl>. The first line of the description is used for multiple "keyword: value" explanations. As a separator we are using the vertical bar. And we are using a special text role "sep" (for separator) for it. As a result it will be rendered as <span class="sep">|</span>. The "keyword:" part is marked up specially as well just to give it the ":aspect:" text role Our css uses the classes to give the whole construct a nice styling.

Attention:

The text roles ascpect and sep (for separator) need to be defined. The usual way of defining them is by having these lines in the Documentation/Includes.rst.txt file. Add these lines:

..  role:: aspect (emphasis)
..  role:: sep (strong)

Sphinx already comes with standard text roles 'emphasis' and 'strong'. 'aspect' and 'sep' inherit their properties and are further specialized.

Example 3: Nicely styled through labels interfere

Let's say you want to place labels in front of each definition list item. This creates anchors you can link to symbolically with the Sphinx "instersphinx" procedure. A downside is that this will intercept the list. Instead, many lists are created. This isn't a problem, if you repeat the 'rst-class' line.

Source:

..  _label-parameterAbc:
..  rst-class:: dl-parameters

parameterAbc
    :sep:`|` :aspect:`Condition:` required
    :sep:`|` :aspect:`Type:` string
    :sep:`|` :aspect:`Default:` ''
    :sep:`|`

    Text describing parameterAbc ...

..  _label-parameterBcd:
..  rst-class:: dl-parameters

parameterBcd
    :sep:`|` :aspect:`Condition:` optional
    :sep:`|` :aspect:`Type:` boolean
    :sep:`|` :aspect:`Default:` false
    :sep:`|`

    Text describing parameterBcd ...

Rendering result:

parameterAbc

| Condition: required | Type: string | Default: '' |

Text describing parameterAbc ...

parameterBcd

| Condition: optional | Type: boolean | Default: false |

Text describing parameterBcd ...

Link example:

Source:

Here we link to :ref:`A link text for parameterAbc <label-parameterAbc>`.

Here we link to :ref:`A link text for parameterBcd <label-parameterAbc>`.

Result:

Here we link to A link text for parameterAbc.

Here we link to A link text for parameterBcd.