Skip to content

Commit

Permalink
Merge pull request #408 from peuter/user-manual
Browse files Browse the repository at this point in the history 
Add RST custom directive descriptions
  • Loading branch information
@ChristianMayer
ChristianMayer committed Sep 4, 2016
2 parents 23ac933 + b56c4ee commit fab187a
Show file tree
Hide file tree
Showing 3 changed files with 185 additions and 4 deletions.
8 changes: 4 additions & 4 deletions .doc/docutils/directives/widget_example.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,12 @@ class WidgetExampleDirective(Directive):
:hide-source: false
:number-lines: 1
<meta design="metal" selector=".widget_container">
<settings design="metal" selector=".widget_container">
<screenshot name="switch_mapping_styling">
<data address="1/4/0">0</data>
</screenshot>
</meta>
<cv-meta>
</settings>
<meta>
<mappings>
<mapping name="OnOff">
<entry value="0">Aus</entry>
Expand All @@ -73,7 +73,7 @@ class WidgetExampleDirective(Directive):
<entry value="0">green</entry>
</styling>
</stylings>
</cv-meta>
</meta>
<switch on_value="1" off_value="0" mapping="OnOff" styling="RedGreen">
<label>Kanal 1</label>
<address transform="DPT:1.001" mode="readwrite">1/1/0</address>
Expand Down
179 changes: 179 additions & 0 deletions doc/manual/de/colab/doc/directives.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
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. |
+-----------------------+-----------------------------------------------------------------------------------------------+

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:

.. code-block:: rst
.. 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:

.. 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>

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 Screenhost 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:

.. code-block:: rst
.. 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 |
+-------------------+-------------------+-------------------+----------------------------------------------------------------------------+
| <settings> | | #text | Untertitel des Beispielcodes |
| <caption> | | | |
+-------------------+-------------------+-------------------+----------------------------------------------------------------------------+
| <settings> | name | Text | Dateiname des Screenshots |
| <screenshot> | | | |
+-------------------+-------------------+-------------------+----------------------------------------------------------------------------+
| <settings> | address | Gruppenaddresse | Sende Daten an diese Adresse bevor der Screenshot gemacht wird |
| <screenshot> +-------------------+-------------------+----------------------------------------------------------------------------+
| <data> | #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.

.. code-block:: rst
.. parameter-information:: switch
.. parameter-information:: switch

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.

.. code-block:: rst
.. elements-information:: switch
.. elements-information:: switch
2 changes: 2 additions & 0 deletions doc/manual/de/colab/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,9 @@ Mithilfe bei der Dokumentation
* Lokales Erzeugen der HTML-Doku, inkl. Screenshots

.. toctree::
:hidden:

doc/directives
todos

Mithilfe bei der Entwicklung
Expand Down

0 comments on commit fab187a

Please sign in to comment.