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.
Links und Referenzen¶
Die Grundsätzliche Syntax von Links enthält einen Title und den Link selbst in folgender Struktur:
`Titel des Links <URL des Links>`__. Natürlich kann man auch auf andere Dokumente innerhalb der Dokumentation verweisen:
:doc:`Titel <relativer/pfad/zum/document>`. Zu beachten ist hierbei, dass man die .rst Dateiendung weglassen muss.
Möchte man also ein Dokument namens dok.rst im Unterverzeichnis test verlinkten, sieht das so aus:
:doc:`test/dok`. Der Titel des Links ist optional, wird er weggelassen, wird der Seitentitel des verlinkten Dokuments
als Titel benutzt (also die Überschrift auf der höchsten Ebene innerhalb des Dokuments).
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
...
<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:
- <settings> Hier werden die Screenshots und Untertitel definiert.
- <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.)
- 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
- linenos: Wenn angegeben, wird der Beispielcode mit Zeilennummern angegeben
- lineno-start: Zahl bei der die Zeilennummern starten sollen (Default: 1)
- scale: Prozentangabe mit der der Screenshot verkleinert werden kann (Default: 100)
- hide-source: true oder false. (Default: false), zeigt den Beispielcode nicht an wenn true
- editor: attributes oder elements. Macht einen Screenshot vom Beispielcode im Editor und nicht vom Widget selbst
- 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 | |
|
#text | Untertitel des Beispielcodes | |
|
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 | |
|
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 | Ä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. | ||
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 | |
|
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 | |
|
name | Text | ||
| type | Text | |||
| flavour | Text | Auswahl der Darstellungsvariante. Siehe auch Flavour. | ||
| color | Text | |||
| 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. | ||
|
Text | Text um bei dem Widget eine Beschreibung darzustellen. | ||
| Element | Attribut | |||
|---|---|---|---|---|
| Struktur | Name | Inhalt | Beschreibung | |
|
transform | Text | ||
| mode | disable, read, write oder readwrite | |||
| variant | Text | |||
| format-pos | Zahl | |||
|
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:
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)