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