The RST-Syntax¶
Heading¶
Headings are defined in RST by “underlining” the text with certain special characters. It should be noted here that the special characters are at least as long as the text itself. Although the RST syntax is relatively tolerant when using the special characters, documentation for the CometVisu documentation set the following definition.
######################
Complete sections
######################
*******
Chapter
*******
Sectionen
=========
Under-sections
---------------
Under-Under-sections
^^^^^^^^^^^^^^^^^^^^^
Paragraph
"""""""""
The complete sections are reserved for the parts Api, user manual and tutorials and may otherwise within the documentation do not occur, all others can be used with care.
Inline Markup¶
If the text in the documentation is to be specially formatted (for example, bold, italic, etc.) or references / links are inserted, a special syntax is required within the text.
For formatting a text, the text is also framed by special characters, so you can use a word, for example. Formatting fat by including in with two asterisks (**bold text**), are more options.
- Bold:
**bold Text**=> bold Text - italic:
*italic Text*=> italic Text - Code:
``Code inside Text``=>Code inside Text
Listings¶
For non-numbered lists, each line is started with *, and in the case
of numbered files with #.. With appropriate Indentation of the
lines, even nested lists are possible.
Links und Referenzen¶
The basic syntax of links contains a title and the link itself
in the following structure: `Title of the link <URL of the link>`.
Of course you can also refer to other documents within the documentation:
:doc: `title <relative/path/to/document>`. Please note that you have
to omit the .rst file extension.
If you want to link a document named dok.rst in the subdirectory test,
it looks like this: :doc:`test/dok`. The title of the link is optional,
it is omitted, the page title of the linked document used as the title
(i.e. the top-level heading within the document).
Directives¶
For things that go beyond plain text (such as images, cues, warnings, etc.), directives are used. In contrast to the already discussed inline markup, these may not appear in the same line as the “normal” text but need a blank line in front of and behind the directive. Directives consist of a name, parameters, options and content. They are always based on the following principle:
.. <name>:: <parameter1> <parameter2> ...
:<option1>: <optionswert1>
:<option2>: <optionswert2>
....
<content to write>
A directive always starts with 2 points followed by a space. This is followed by the name and then directly, without Space 2 colons. It should also be noted that the options are enclosed by colons and by a blank line are separate from the content, and options and content are indented.
The only thing that is mandatory is the name. Parameters, options and content are optional and different in quantity and in the presence of directive to directive. In the following the most important directives are presented.
Text-Block¶
Simple directives that can be used to create a color-coded text block with a given title, to define notes, information, warnings, etc. These directives have no parameters and options just a content.
Possible text blocks are: attention, caution, danger, error, hint, important, note, tip, warning. So if you want to give the reader e.g. on something important hints, you can write the following.
.. IMPORTANT::
This is an important note.
What will be formatted like this:
Important
This is an important note.
Images¶
Images are included with the figure directive. There is also an image directive, but the figure directive allows complex captions.
.. figure:: <path to image>
This is the caption
The complete syntax of this directive can be found in the official Documentation
Own directives¶
In addition to the existing Sphinx/Docutils directives, there are also some special directives in the CometVisu that help to keep the documentation more up-to-date.
The following directives are currently supported:
| Name | Description |
|---|---|
| widget-example | Provides sample code for widgets from which screenshots can be automatically created. |
| parameter-information | Displays all attributes of a widget with allowed values and short explanation as a table. |
| elements-information | Shows all allowed sub-elements of a widget including their attributes as a table. |
| api-doc | Includes information from the source code documentation (@author and @since). |
| replaces | This determines which pages of the old wiki replace this page |
The widget-example Directive¶
The widget-example directive allows example code of a CometVisu config from which one or more screenshots will be automatically generated later and integrated into the documentation together with the example code.
The following example:
.. widget-example::
<settings>
<screenshot name="switch_complete">
<caption>Switch with mapping + styling</caption>
<data address="1/4/0">1</data>
</screenshot>
</settings>
<meta>
<mappings>
<mapping name="OnOff">
<entry value="0">Aus</entry>
<entry value="1">An</entry>
</mapping>
</mappings>
<stylings>
<styling name="RedGreen">
<entry value="1">red</entry>
<entry value="0">green</entry>
</styling>
</stylings>
</meta>
<switch on_value="1" off_value="0" mapping="OnOff" styling="RedGreen" bind_click_to_widget="true">
<label>Kanal 1<icon name="control_on_off"/></label>
<address transform="DPT:1.001" mode="readwrite">1/1/0</address>
<address transform="DPT:1.001" mode="read">1/4/0</address>
</switch>
generates this entry in the documentation:
Switch with mapping + styling
...
<meta>
<mappings>
<mapping name="OnOff">
<entry value="0">Aus</entry>
<entry value="1">An</entry>
</mapping>
</mappings>
<stylings>
<styling name="RedGreen">
<entry value="1">red</entry>
<entry value="0">green</entry>
</styling>
</stylings>
</meta>
...
<switch on_value="1" off_value="0" mapping="OnOff" styling="RedGreen" bind_click_to_widget="true">
<label>Kanal 1<icon name="control_on_off"/></label>
<address transform="DPT:1.001" mode="readwrite">1/1/0</address>
<address transform="DPT:1.001" mode="read">1/4/0</address>
</switch>
The content of the directive is based on the structure of the normal CometVisu configuration file and is also an XML document. It basically consists of 3 areas:
- <settings> Here are the screenshots and subtitles defined.
- <meta> Everything is allowed here, which is also allowed within the <meta> element of the configuration file (for example loading plugins, defining mappings, styling, etc.)
- All other Anything that is not inside a <settings> or <meta> element is interpreted as a sample code. Everything that is allowed within a <page> element of the configuration file (such as widgets, groups, etc.) is allowed here.
The areas 1 and 2 are optional and may be omitted, so if e.g. only 1 screenshot of the example code without subtitles required, the <settings> - part can also be omitted.
In addition, there are various options with which the appearance of the example code and the corresponding screenshot can be influenced.
- linenos: If specified, the example code is given with line numbers
- lineno-start: Number at which the line numbers should start (default: 1)
- scale: Percentage with which the screen host can be reduced (default: 100)
- hide-source: true or false. (Default: false), does not display the sample code if true
- editor: attributes or elements. Take a screenshot of the example code in the editor, not the widget itself
- align: left, center or right. Defines the position of the screenshot (Default: left)
A complete example with all options:
.. widget-example::
:linenos:
:linenos-start: 1
:scale: 75
:hide-source: true
:editor: attributes
:align: center
....
The <settings>¶
This area is defined by the <settings> element and this can be refined by attributes and subelements.
| Element | Attribut | ||
|---|---|---|---|
| Name | Content | Description | |
| <settings> | design | Name of a design| In which design the screenshot should be taken (default: metal) | |
| selector | Css-Selector | Defines the area of the screenshot | |
| sleep | number | Initial wait time in ms before the screenshot is taken | |
|
#text | Subtitles of the example code | |
|
name | text | File name of the screenshot |
| clickpath | CSS-Selector | CSS path to an item to be clicked before the screenshot | |
| waitfor | CSS-Selector | CSS path to an item that should be visible before the screenshot | |
| sleep | number | Waiting time between sending the data and screenshot | |
|
address | group address | Send data to this address before taking the screenshot |
| type | float or int | If real numbers need to be sent | |
| #text | text | Content of the data to be sent | |
The parameter-information Directive¶
This directive automatically creates a table summary with the widget’s attributes. These data are read from the schema definition (visu_config.xsd). This directive has no options, no content, and only one parameter that contains the widget name.
This example creates the attribute table for the switch widget.
.. parameter-information:: switch
| Element | Attribute | |||
|---|---|---|---|---|
| Name | Content | Description | ||
| switch | styling | string | Change the color of the dispayed value depending on its value. See also Styling | |
| mapping | string | Map the bus value to a different value, text or symbol for displaying. See also Mapping | ||
| on_value | string | Value of the “on” state. Defaults to “1”. | ||
| off_value | string | Value of the “off” state. Defaults to “0”. | ||
| align | left, right or center | |||
| flavour | string | Selection of a display variant. See also Flavour. | ||
| bind_click_to_widget | true or false | use the whole widget area to react on click events | ||
| class | string | Add this value to the CSS class so that it can be formated by a user provided style sheet. | ||
The elements-information Directive¶
This directive automatically creates a table summary with the allowed sub-elements of a widget. These data are read from the schema definition (visu_config.xsd). This directive has no options, no content, and only one parameter that contains the widget name.
This example creates the element table for the switch widget.
.. elements-information:: switch
| Element | Attribute | |||
|---|---|---|---|---|
| Structure | Name | Content | Description | |
|
colspan | decimal | Amount of coloumns this widget sould be wide. | |
| colspan-m | decimal | Overrules the amount of coloumns on a medium screen. | ||
| colspan-s | decimal | Overrules the amount of coloumns on a small screen. | ||
| rowspan | decimal | Amount of rows this widget should be high. | ||
| x | string | Horizontal position of the widget for 2D pages. | ||
| x-s | string | Horizontal position of the widget for 2D pages on a small screen. | ||
| x-m | string | Horizontal position of the widget for 2D pages on a medium screen. | ||
| y | string | Vertical position of the widget for 2D pages. | ||
| y-s | string | Vertical position of the widget for 2D pages on a small screen. | ||
| y-m | string | Vertical position of the widget for 2D pages on a medium screen. | ||
| z | string | Reserved for future use. | ||
| width | string | Width for the widget for 2D pages. | ||
| width-s | string | Width for the widget for 2D pages on a small screen. | ||
| width-m | string | Width for the widget for 2D pages on a medium screen. | ||
| scale | true or false | Enable/Disable scaling layout values relative to backdrop on 2d pages (default: true). | ||
| scale-s | true or false | Enable/Disable scaling layout values relative to backdrop on 2d pages on a small screen (default: true). | ||
| scale-m | true or false | Enable/Disable scaling layout values relative to backdrop on 2d pages on a medium screen (default: true). | ||
| Element | Attribute | |||
|---|---|---|---|---|
| Structure | Name | Content | Description | |
|
name | string | ||
| type | string | |||
| flavour | string | Selection of a display variant. See also Flavour. | ||
| color | string | |||
| styling | string | Change the color of the dispayed value depending on its value. See also Styling | ||
| class | string | Add this value to the CSS class so that it can be formated by a user provided style sheet. | ||
|
string | Text to display a label for the widget. | ||
| Element | Attribute | |||
|---|---|---|---|---|
| Structure | Name | Content | Description | |
|
transform | string | ||
| mode | disable, read, write or readwrite | |||
| variant | string | |||
| format-pos | decimal | |||
|
string | The GA (like: 12/0/7) for KNX-backends or the item name for openHAB-backend | ||
The api-doc Directive¶
This directive reads important information from the source code
documentation of a widget or plugin. Currently these are the values
of the @author and @since specifications.
Important
It is important that the name of the widget corresponds exactly
to the name of the source code file without file extension, e.g.
for structure/pure/Switch.js use .. api-doc :: Switch
(case-sensitive). For plugins, the folder name of the plugin
must be specified, e.g. for plugins/colorchooser/ you
take .. api-doc :: colorchooser
Example for the Switch-Widget:
.. api-doc:: Switch
generates the following content:
The replaces Directive¶
This directive defines which pages of the old wiki are replaced by this manual page. Several wiki pages can be specified. This directive does not add any content to the documentation, but is used to automatically create redirects.
.. replaces:: CometVisu/0.8.x/widgets/switch/de/
CometVisu/0.8.0/switch/de
CometVisu/Widget/switch/de
CometVisu/switch
CometVisu/switch_(Deutsch)