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 and References

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:

...
<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	Attribute
	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
<settings> <caption>		#text	Subtitles of the example code
<settings> <screenshot>	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
<settings> <screenshot> <data>	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 displayed 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 formatted by a user provided style sheet.
	format	string	Formatting of the value (printf syntax).

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
switch layout	colspan	decimal	Amount of columns this widget should be wide.
	colspan-m	decimal	Overrules the amount of columns on a medium screen.
	colspan-s	decimal	Overrules the amount of columns 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
switch label icon	name	string	Name of the icon registration.
	type	string
	flavour	string	Selection of a display variant. See also Flavour.
	color	string	Color of the icon in CSS notation (e.g. #1188FF).
	styling	string	Change the color of the displayed value depending on its value. See also Styling
	class	string	Add this value to the CSS class so that it can be formatted by a user provided style sheet.
switch label #text		string	Text to display a label for the widget.

Element	Attribute
Structure	Name	Content	Description
switch address	transform	string	Transformation of the bus system value to be shown.
	mode	disable, read, write or readwrite	“disable” deactivates the communication, “read” will only fetch data from the backend, “write” will only write to it and an address with “readwrite” will be both, read from and written to.
	variant	string
	format-pos	decimal	Position for format string when multiple addresses are used.
	selector	string	Only MQTT: JSON selector
	qos	decimal	Only MQTT: QoS
	retain	true or false	Only MQTT: retain flag
	ignore-error	true or false	Only MQTT: ignore decode errors.
switch address #text		string	The GA (like: 12/0/7) for KNX-backends, the item name for openHAB-backend or the MQTT topic

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/clock/ you take .. api-doc :: clock

Example for the Switch-Widget:

.. api-doc:: Switch

generates the following content:

Author: Christian Mayer
Available since: 0.8.0 (2012)

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)