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 ensprechender 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 Eigentwicklungen 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äst 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 beinflusst 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 Screenhost 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 Gruppenaddresse 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  
mapping Text Ordnet den Werten vom Bus andere zur Anzeige zu.
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.

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.
y Text Vertikale Position des Widgets auf 2D Seiten.
z Text Für zukünftige Anwendungen reserviert.
width Text Breite des Widgets auf 2D Seiten.
Element Attribut
Struktur Name Inhalt Beschreibung
switch
  • label
  • icon
 name Text  
type Text  
flavour Text Auswahl der Darstellungsvariante. Siehe auch Flavour.
color Text  
styling Text  
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  
mode disable, read, write oder readwrite  
variant Text  
format-pos Zahl  
switch
  • address
  • #text
   Text Die Gruppenaddresse (z.B: 12/0/7) bei KNX-Backends oder der Item-Name beim openHAB-Backend.

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/colorchooser/ nimmt man .. api-doc:: colorchooser

Beispiel für das Switch-Widget:

.. api-doc:: Switch

erzeugt folgenden Inhalt:

Verfügbar seit Version: 0.8.0 (2012)
Autor: Christian Mayer

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)