Die RST-Syntax

Überschriften

Überschriften werden in RST durch „unterstreichen“ des Textes mit bestimmten Sonderzeichen definiert. Zu beachten ist hier, das die Sonderzeichen mindestens genauso lang sind wie der Text selbst. Auch wenn die RST-Syntax bei der Benutzung der Sonderzeichen relativ tolerant ist, wird für die CometVisu Dokumentation folgende Definition festgelegt.

######################
Komplette Teilbereiche
######################

*******
Kapitel
*******

Sektionen
=========

Unter-Sektionen
---------------

Unter-Unter-Sektionen
^^^^^^^^^^^^^^^^^^^^^

Paragraphen
"""""""""""

Die kompletten Teilbereiche, sind den Teilen Api, Benutzerhandbuch und Tutorials vorbehalten und dürfen ansonsten innerhalb der Dokumentation nicht vorkommen, alle anderen können mit bedacht verwendet werden.

Inline Markup

Soll der Text in der Dokumentation besonders formatiert (z.B. fett, kursiv, usw.) oder Referenzen / Links eingebaut werden benötigt man eine spezielle Syntax innerhalb des Textes.

Zur Formatierung eines Textes, wird der Text ebenfalls von Sonderzeichen umrahmt, so kann man ein Wort z.B. fett formatieren indem man in mit zwei Sternchen umfasst (**fetter Text**), weitere Möglichkeiten sind.

  • Fett: **fetter Text** => fetter Text

  • Kursiv: *kursiver Text* => kursiver Text

  • Code-Beispiele: ``Code im Text`` => Code im Text

Listen

Für unnummerierte Listen wird jede Zeile mit * gestartet, bei nummerierten mit #.. Mit entsprechender Einrückung der Zeilen sind auch verschachtelte Listen möglich.

Direktiven

Für Dinge die über reinen Text hinaus gehen (z.B. Bilder, Hinweise, Warnungen, usw.) werden Direktiven verwendet. Diese dürfen im Gegensatz zum bereits behandelten inline Markup nicht in der selben Zeile wie der „normale“ Text stehen sondern benötigen eine Leerzeile vor und hinter der Direktive. Direktiven bestehen aus einem Namen, Parametern Optionen und dem Inhalt und sind immer nach folgendem Prinzip aufgebaut:

.. <name>:: <parameter1> <parameter2> ...
     :<option1>: <optionswert1>
     :<option2>: <optionswert2>
     ....

     <Inhalt der Direktive>

Eine Direktive startet immer mit 2 Punkten gefolgt von einem Leerzeichen. Darauf folgt der Name und dann direkt, ohne Leerzeichen 2 Doppelpunkte. Weiterhin zu beachten ist, dass die Optionen durch Doppelpunkte eingefasst und durch eine Leerzeile vom Inhalt getrennt sind, außerdem sind Optionen und Inhalt eingerückt.

Das einzige, was zwingend erforderlich ist, ist der Name. Parameter, Optionen und Inhalt sind optional und unterscheiden sich in Menge und vorhandensein von Direktive zu Direktive. Im folgenden werden nun die wichtigsten Direktiven vorgestellt.

Text-Blöcke

Einfache Direktiven, mit denen ein farblich hervorgehobener Textblock mit vorgegebenem Titel erstellt werden können, um damit Hinweise, Informationen, Warnungen usw. zu definieren. Diese Direktiven haben keine Parameter und Optionen, lediglich einen Inhalt.

Mögliche Textblöcke sind: attention, caution, danger, error, hint, important, note, tip, warning. Möchte man den Leser also z.B. auf etwas wichtiges Hinweisen, kann man folgendes schreiben.

.. IMPORTANT::

    Dies ist ein wichtiger Hinweis.

Was dann so formatiert wird:

Wichtig

Dies ist ein wichtiger Hinweis.

Bilder

Bilder werden mit der figure-Direktive eingebunden. Es gibt zwar auch eine image-Direktive, aber die figure-Direktive erlaubt komplexe Bildunterschriften.

.. figure:: <pfad-zum-bild>

    Dies ist die Bildunterschift

Die komplette Syntax dieser Direktive kann in der offiziellen Dokumentation nachgelesen werden.

Eigene Direktiven

Neben den vorhandenen Sphinx/Docutils Direktiven werden in der CometVisu Dokumentation auch einige Direktiven genutzt, die dabei helfen, die Dokumentation einfacher auf einem aktuellen Stand zu halten. Folgende Direktiven werden zur Zeit unterstützt:

Name

Beschreibung

widget-example

Ermöglicht Beispielcode für Widgets aus dem automatisch Screenshots erstellt werden kann.

parameter-information

Zeigt alle Attribute eines Widgets mit erlaubten Werten und kurzer Erklärung als Tabelle an.

elements-information

Zeigt alle erlaubten Unter-Elemente eines Widgets inkl. deren Attributen als Tabelle an.

api-doc

Bindet Informationen aus der Source-Code Dokumentation ein (@author und @since)

replaces

Hiermit lässt sich festlegen, welche Seiten des alten Wikis diese Seite ersetzt

Die widget-example Direktive

Die widget-example Direktive erlaubt Beispiel-Code einer CometVisu config aus der später vollautomatisch einer oder mehrere Screenshots generiert werden und zusammen mit dem Beispiel-Code in die Dokumentation eingebunden werden.

Das folgende Beispiel:

.. widget-example::

    <settings>
        <screenshot name="switch_complete">
            <caption>Switch mit 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>

erzeugt diesen Eintrag in der Dokumentation:

Switch mit mapping + styling

Switch mit 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>

Der Inhalt der Direktive orientiert sich am Aufbau der normalen CometVisu Konfigurationsdatei und ist ebenfalls ein XML-Dokument. Er besteht im Wesentlichen aus 3 Bereichen:

  1. <settings> Hier werden die Screenshots und Untertitel definiert.

  2. <meta> Hier ist alles erlaubt, was auch innerhalb des <meta>-Elements der Konfigurationsdatei erlaubt ist (z.B. Laden von Plugins, Definition von Mappings, Stylings usw.)

  3. Alles andere Alles was nicht innerhalb eines <settings> oder <meta>-Elements ist, wird als Beispielcode interpretiert. Hier ist also alles erlaubt, was innerhalb eines <page>-Elements der Konfigurationsdatei erlaubt ist (z.B. Widgets, Groups, usw.)

Die Bereiche 1. und 2. sind optional und können auch weggelassen werden, wenn man also z.B. nur 1 Screenshot vom Beispielcode ohne Untertitel benötigt kann der <settings>-Teil auch weggelassen werden.

Darüber hinaus gibt es noch diverse Optionen mit denen das Aussehen des Beispiel-Codes und des zu gehörigen Screenshots beeinflusst werden können

  1. linenos: Wenn angegeben, wird der Beispielcode mit Zeilennummern angegeben

  2. lineno-start: Zahl bei der die Zeilennummern starten sollen (Default: 1)

  3. scale: Prozentangabe mit der der Screenshot verkleinert werden kann (Default: 100)

  4. hide-source: true oder false. (Default: false), zeigt den Beispielcode nicht an wenn true

  5. editor: attributes oder elements. Macht einen Screenshot vom Beispielcode im Editor und nicht vom Widget selbst

  6. align: left, center oder right. Definiert die Position des Screenshots (Default: left)

Ein vollständiges Beispiel mit allen Optionen:

.. widget-example::
    :linenos:
    :linenos-start: 1
    :scale: 75
    :hide-source: true
    :editor: attributes
    :align: center

    ....

Der <settings>-Bereich

Dieser Bereich wird definiert durch das <settings>-Element und dieses kann durch Attribute und Unterelemente verfeinert werden.

Element

Attribut

Name

Inhalt

Beschreibung

<settings>

design

Name eines Designs

In welchem Design der Screenshot aufgenommen werden soll (Default: metal)

selector

Css-Selector

Definiert den Bereich des Screenshots

sleep

Zahl

Initiale Wartezeit in ms bevor der Screenshot aufgenommen wird
<settings>

<caption>

#text

Untertitel des Beispielcodes
<settings>

<screenshot>

name

Text

Dateiname des Screenshots

clickpath

CSS-Selector

CSS-Pfad zu einem Element, das angeklickt werden soll vor dem Screenshot

waitfor

CSS-Selector

CSS-Pfad zu einem Element, das sichtbar sein soll vor dem Screenshot

sleep

Zahl

Wartezeit zwischen Senden der Daten und Screenshot
<settings>
<screenshot>

<data>

address

Gruppenadresse

Sende Daten an diese Adresse bevor der Screenshot gemacht wird

type

float oder int

Falls echte Zahlenwerte gesendet werden müssen

#text

Text

Inhalt der Daten die gesendet werden sollen

Die parameter-information Direktive

Diese Direktive erzeugt automatisch eine Tabellenübersicht mit den Attributen des Widgets. Diese Daten werden aus der Schema-Definition (visu_config.xsd) ausgelesen. Diese Direktive hat keine Optionen und keinen Inhalt und nur einen Parameter der den Widget-Namen enthält.

Dieses Beispiel erzeugt die Attribut-Tabelle für das Switch-Widget.

.. parameter-information:: switch

Element

Attribut

Name

Inhalt

Beschreibung

switch

styling

Text

Ändert die Farbe des angezeigten Wertes abhängig vom Wert selbst. Siehe auch Styling

mapping

Text

Ordnet den Werten vom Bus andere Werte, Texte oder Symbole zur Anzeige zu. Siehe auch Mapping

on_value

Text

Wert für den An-Zustand. Default ist „1“.

off_value

Text

Wert für den Aus-Zustand. Default ist „0“.

align

left, right oder center

flavour

Text

Auswahl der Darstellungsvariante. Siehe auch Flavour.

bind_click_to_widget

true oder false

Beim Aktivieren dieser Option wird die gesamte Widget Fläche als Schaltfläche genutzt

class

Text

Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.

format

Text

Formatierung des Wertes (printf-Syntax).

Die elements-information Direktive

Diese Direktive erzeugt automatisch eine Tabellenübersicht mit den erlaubten Unter-Elementen eines Widgets. Diese Daten werden aus der Schema-Definition (visu_config.xsd) ausgelesen. Diese Direktive hat keine Optionen und keinen Inhalt und nur einen Parameter der den Widget-Namen enthält.

Dieses Beispiel erzeugt die Element-Tabelle für das Switch-Widget.

.. elements-information:: switch

Element

Attribut

Struktur

Name

Inhalt

Beschreibung
switch

  • layout

colspan

Zahl

Spaltenanzahl für dieses Widget.

colspan-m

Zahl

Übersteuert die Spaltenanzahl auf mittleren (medium) Browser Größen.

colspan-s

Zahl

Übersteuert die Spaltenanzahl auf kleinen (small) Browser Größen.

rowspan

Zahl

Zeilenanzahl für dieses Widget.

x

Text

Horizontale Position des Widgets auf 2D Seiten.

x-s

Text

Horizontale Position des Widgets auf 2D Seiten auf kleinen (small) Browser Größen.

x-m

Text

Horizontale Position des Widgets auf 2D Seiten auf mittleren (medium) Browser Größen.

y

Text

Vertikale Position des Widgets auf 2D Seiten.

y-s

Text

Vertikale Position des Widgets auf 2D Seiten auf kleinen (small) Browser Größen.

y-m

Text

Vertikale Position des Widgets auf 2D Seiten auf mittleren (medium) Browser Größen.

z

Text

Für zukünftige Anwendungen reserviert.

width

Text

Breite des Widgets auf 2D Seiten.

width-s

Text

Breite des Widgets auf 2D Seiten auf kleinen (small) Browser Größen.

width-m

Text

Breite des Widgets auf 2D Seiten auf mittleren (medium) Browser Größen.

scale

true oder false

Automatische Anpassung der Layout-Werte auf Basis der Skalierung des Backdrops ein/-ausschalten (Standardeinstellung: true).

scale-s

true oder false

Automatische Anpassung der Layout-Werte auf Basis der Skalierung des Backdrops ein/-ausschalten auf kleinen (small) Browser Größen (Standardeinstellung: true).

scale-m

true oder false

Automatische Anpassung der Layout-Werte auf Basis der Skalierung des Backdrops ein/-ausschalten auf mittleren (medium) Browser Größen (Standardeinstellung: true).

Element

Attribut

Struktur

Name

Inhalt

Beschreibung
switch

  • label

  • icon

name

Text

Name unter dem das Icon registriert ist.

type

Text

flavour

Text

Auswahl der Darstellungsvariante. Siehe auch Flavour.

color

Text

Farbe des Icon in CSS Notation (z.B. #1188FF).

styling

Text

Ändert die Farbe des angezeigten Wertes abhängig vom Wert selbst. Siehe auch Styling

class

Text

Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.
switch

  • label

    • #text

Text

Text um bei dem Widget eine Beschreibung darzustellen.

Element

Attribut

Struktur

Name

Inhalt

Beschreibung
switch

  • address

transform

Text

Umwandlung des Bus-System Wertes um angezeigt werden zu können.

mode

disable, read, write oder readwrite

„disable“ deaktiviert die Kommunikation, bei „read“ wird nur vom Backend gelesen, bei „write“ wird nur geschrieben und „readwrite“ wird die Adresse zum Lesen und zum Schreiben verwendet.

variant

Text

format-pos

Zahl

Position für Format-String wenn mehrere Adressen gleichzeitig genutzt werden.

selector

Text

Nur MQTT: JSON Selektor

qos

Zahl

Nur MQTT: QoS

retain

true oder false

Nur MQTT: retain Flag

ignore-error

true oder false

Nur MQTT: ignoriere Dekodierfehler.
switch

  • address

    • #text

Text

Die Gruppenadresse (z.B: 12/0/7) bei KNX-Backends, der Item-Name beim openHAB-Backend oder das Topic bei MQTT.

Die api-doc Direktive

Diese Direktive liest wichtige Informationen aus der Source-Code Dokumentation eines Widgets oder Plugins. Momentan sind das die Werte der @author und @since Angaben.

Wichtig

Wichtig ist hierbei, dass der Name des Widgets exakt dem Namen der Sourcecode-Datei ohne Dateiendung entspricht, also z.B. für structure/pure/Switch.js nimmt man .. api-doc:: Switch (Groß-/Kleinschreibung beachten). Bei Plugins muss der Ordnername des Plugins angegeben werden, also z.B. für plugins/clock/ nimmt man .. api-doc:: clock

Beispiel für das Switch-Widget:

.. api-doc:: Switch

erzeugt folgenden Inhalt:

Autor: Christian Mayer
Available since: 0.8.0 (2012)

Die replaces Directive

Durch diese Direktive lasst sich definieren, welche Seiten des alten Wikis durch diese Handbuch-Seite ersetzt werden. Es können mehrere Wiki-Seiten angegeben werden. Diese Direktive fügt der Dokumentation keinen Inhalt hinzu, sondern wird dazu verwendet automatisch Weiterleitungen zu erstellen.

.. replaces:: CometVisu/0.8.x/widgets/switch/de/
    CometVisu/0.8.0/switch/de
    CometVisu/Widget/switch/de
    CometVisu/switch
    CometVisu/switch_(Deutsch)