Vorschlag für Verbesserungen der Dokumentation

[peuter]

Die Definition des switch beginnt in Zeile 851. Darin finden sich auch alle 7 Attribute, deren Type entweder an Ort und Stelle definiert ist, wie z.B. bei den on_value/off_value Attributen. Alle anderen Attribute werden woanders definiert, zu erkennen am "ref", wie z.B.

<xsd:attribute ref="styling" use="optional" />

Da muss man dann nach <xsd:attribute name="styling" suchen und wird in Zeile 160 fündig. Als Faustregel:

Alle <xsd:attribute> Einträge die ein "name"-Attribute Eintrag haben, können mit <xsd:annotation><xsd:documentation>... versehen werden. Wenn sie ein "ref"-Attribut haben, dann muss man die Stelle suchen wo die Attribute definiert werden (wie oben bereits beschrieben) und dort die Dokumentation einfügen.

[Chris M.]

Nehmen wir mal exakt diese Version: https://github.com/CometVisu/CometVi...isu_config.xsd
(Das ist stand jetzt die aktuellste - aber jede zukünftige Änderung könnte ganz leicht die Zeilennummern ändern)

Nun fängst man einfach mal mit einer Suche nach "switch" an.

-> Zeile 796: da wird gesagt, dass switch zur Gruppe "Widgets" gehört. Interessant - aber hier erst mal nicht von Belang
-> Zeile 851:

<xsd:complexType name="switch">

=> Volltreffer!

Da steht nun, dass das switch ein paar Elemente enthalten kann:

<xsd:sequence>
<xsd:element name="layout" type="layout" minOccurs="0" maxOccurs="1"/>
<xsd:element name="label" type="label" minOccurs="0" maxOccurs="1"/>
<xsd:element name="address" type="address" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>

und nun kommen schon die Attribute:

<xsd:attribute ref="styling" use="optional" />
<xsd:attribute ref="mapping" use="optional" />
<xsd:attribute name="on_value" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation xml:lang="en">Value of the "on" state. Defaults to "1".</xsd:documentation>
<xsd:documentation xml:lang="de">Wert für den An-Zustand. Default ist "1".</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute name="off_value" type="xsd:string" use="optional">
<xsd:annotation>
<xsd:documentation xml:lang="en">Value of the "off" state. Defaults to "0".</xsd:documentation>
<xsd:documentation xml:lang="de">Wert für den Aus-Zustand. Default ist "0".</xsd:documentation>
</xsd:annotation>
</xsd:attribute>
<xsd:attribute ref="align" use="optional" />
<xsd:attribute ref="flavour" use="optional" />
<xsd:attribute ref="bind_click_to_widget" use="optional"/>

Wie Du hier sehen kannst, gibt es nun welche, die schon einen Text haben, wie z.B. on_value, aber auch welche, wo es nicht so klar ist, wie z.B. align oder mapping.

Dort ist es nicht klar, da diese Attribute hier nicht definiert sind, sondern eine Referenz auf eine Definition wo anders sind.

Also neue Suche. Starten wir mal mit mapping: Zeile 153 wird fündig - und eine Doku ist auch schon da.
Nächster Versuch align: Zeile 247 wird fündig, hat aber keine Doku.

Wird's so etwas klarer?

[SirTobiIV]

Super erklärt. Ist es gedacht die xsd direkt zu editieren? Ich dachte man solle im Quelltext des einzelnen Widgets editieren.

Ich bastel übrigens gerade daran Eclipse für github direkt einzurichten.

[Chris M.]

Die XSD ist (zumindest aktuell) ein statisches Dokument und von Hand erzeugt. Also spricht nichts dagegen die Datei per Hand zu editieren

Der Quelltext der einzelnen Widgets ist wichtig für die automatisch generierte API Doku.

[peuter]

Ist es gedacht die xsd direkt zu editieren? Ich dachte man solle im Quelltext des einzelnen Widgets editieren.

Es gibt verschiede Stellen an denen Dokumentation hinzugefügt werden kann. Ich nehme mal wieder das Switch-Widget als Beispiel, weil es das einzigste ist, was an allen Stellen bereits dokumentiert ist.

1. Im Quelltext des Widgets:
https://github.com/CometVisu/CometVi...pure/Switch.js
Ist die Sourcecode Dokumentation in englisch geschrieben und richtet sich in erster Linie an Entwickler. Was dort steht landet am Ende hier:
http://test.cometvisu.org/CometVisu/...re_Switch.html

2. Im Quelltext des Benutzerhandbuchs:
https://raw.githubusercontent.com/Co...itch/index.rst
Das richtet sich an alle Anwender der Inhalt landet am Ende hier:
http://test.cometvisu.org/CometVisu/...tch/index.html

3. In der XSD gibt es Annotationen, die Erklärungen zu den Attributen eines Widgets liefern. Dieser werden sowohl im Editor als auch im Benutzerhandbuch genutzt (automatisch, muss man nur in die XSD schreiben da wird das dann vom Handbuch und vom Editor ausgelesen)

Dokumentieren kann man an allen drei Stellen, wobei aber die Priorität in umgekehrter Reihenfolge sein sollte. Also Punkt 3, die XSD zu vervollständigen sollte der erste Schritt sein, danach bzw. parallel Punkt 2. das Benutzerhandbuch und die Sourcecode-Doku hat die niedrigste Priorität.

[SirTobiIV]

Ich habe mir nun nen github Client installiert und synchronisiert (den develop-branch).
Leider sehe ich aber die aktuellsten Änderungen, die peuter in der visu_config.xsd gemacht hat bei mir auf dem Rechner lokal nicht. Habe ich einen falschen Branch geclont?

Mit SVN habe ich schonmal gearbeitet. Bei Github tue ich mir aber schon schwer zu verstehen, wie denn
a) erreicht wird, dass ich an der aktuellsten version weiterarbeite
b) wie verhindert wird, dass Arbeit doppelt gemacht wird. Seht ihr, woran ich arbeite? Ich kann soweit ich das sehe den Sorucecode ja nicht auschecken?

[peuter]

a) erreicht wird, dass ich an der aktuellsten version weiterarbeite

Pullrequest kannst Du auch in die Gegenrichtung machen, also vom CometVisu-Repository in Deinen Fork, damit bekommst die die letzten Änderungen

b) wie verhindert wird, dass Arbeit doppelt gemacht wird. Seht ihr, woran ich arbeite?

Bei verteilten Softwareprojekten kann man nie sehen woran der einzelne jeweils lokal arbeitet. Wenn man größere Änderungen vorhat, sollte man das irgendwo kundtun (hier im Forum oder als Issue auf github), bei kleineren Dingen stellt man ja in der Regeln schnell einen Pull request und es ist eher unwarscheinlich, dass genau in dem Moment jemand parallel an der selben Änderung gearbeitet hat.

Ich kann soweit ich das sehe den Sorucecode ja nicht auschecken?

Das was bei SVN das auschecken war ist bei git das clonen (auch wenn es im Detail was anderes ist). Wenn du ein Repository clonest hast du die Sourcen doch auf deinem Rechner.

[Chris M.]

Wenn man größere Änderungen vorhat, sollte man das irgendwo kundtun (hier im Forum oder als Issue auf github), bei kleineren Dingen stellt man ja in der Regeln schnell einen Pull request und es ist eher unwarscheinlich, dass genau in dem Moment jemand parallel an der selben Änderung gearbeitet hat.

Und gerade bei Kleinigkeiten bietet sich auch https://gitter.im/CometVisu/CometVisu_DE an. Da das ein Chat ist, kann man da schnell Themen abstimmen.

[Chris M.]

Das mit dem Pull Request scheint ja schon mal gut funktioniert zu haben

Wie Du nun auf der Seite des Requests (https://github.com/CometVisu/CometVisu/pull/395) sehen kannst, kann man dort über den Request diskutieren und sogar zu einzelnen Zeilen ein Kommentar hinzufügen.

Du kannst nun dort z.B. Antworten warum dein Vorschlag besser ist als das, was der Reviewer meint, evtl. stimmst Du ihn um und er Pullt den Request.
Oder Du kannst den Kommentar aufgreifen und den Pull Request entsprechend ändern - was ganz einfach ist: einfach bei Dir in dem Branch wo der PR her kommt die Datei anpassen und neu "einchecken" (Kommandozeile: add + commit + push).

[SirTobiIV]

Ja. Allerdings habe ich das ganze online editiert, was recht umständlich ist, da weder die Suche funktioniert, noch gibt es farbige Hervorhebungen oder gar eine Syntaxkorrektur.

Editieren mit eclipse klappt noch nicht. Direkte Verbindung mit Github will nicht und wenn ich das Projekt offline öffne, dann legte eclipse weitere projektdateien an, die dann im Git auftauchen.

[peuter]

Editieren mit eclipse klappt noch nicht. Direkte Verbindung mit Github will nicht und wenn ich das Projekt offline öffne, dann legte eclipse weitere projektdateien an, die dann im Git auftauchen.

Solche Dateien kannst Du in die .gitignore Datei (Im obersten Vertzeichnis des CometVisu-Projekts) eintragen, dann werden die von Git ignoriert.

[Wurschtel]

Oh weh, oh weh ... das wird nun richtig kompliziert!

Ich hatte mir mal ein Lesezeichen auf "http://peuter.github.io/CometVisu/de/manual/" gelegt, dachte dort den aktuellen Bearbeitungsstand sehen zu können, um dann hin und wieder ... wo auch immer ... die eine oder andere Zeile hinzuzufügen, die dann gegengelesen und akzeptiert oder verworfen wird.

[peuter]

Also der aktuelle Stand ist nun unter http://test.cometvisu.org/CometVisu/...ual/index.html zu finden. Und so kompliziert ist das jetzt auch nicht z.B. die Sache mit der gitignore Änderung muss nur einmal von jemandem für Eclipse gemacht werden, dann funktioniert das für alle, weil es ab dann im CometVisu-Repository ist. Wir sind ja immer noch in der Findungsphase, wie man es am besten macht und wie man den Git-Neulingen das Leben so einfach wie möglich machen kann. Die Anfangsprobleme müssen halt erstmal gelöst werden und dann der einfachste Weg auch mal vernünftig dokumentiert werden.

[SirTobiIV]

Ich folge dem Vorschlag von peuter zuerst eine Beschreibung für jedes Attribut aller widgets zu erstellen, damit man in etwa erahnen kann, was das Attribut bewirkt.

Ich gebe wurstl recht, dass Git glaube ich für die meisten User eine zu große Hürde darstellt. Allerdings unterstelle ich dem cometvisu User schon eine gewisse Technikaffinität.

@wurstel: ich kann dir anbieten, dass ich deine Vorschläge/Widgetbeschreibungen in die Doku einpflege, falls du das nicht schaffen solltest. PM an mich.

[Wurschtel]

Okay .... dann ist nun also http://test.cometvisu.org/CometVisu/...ual/index.html der aktuelle Stand.

Wenn ich jetzt nun für die drei darin zu findenden Absätze

Die CometVisu Konfigurationsdatei ist eine XML Datei, die im Unterverzeichnis “config” der CometVisu-Installation (normal also unter /var/www/visu/config) liegt.

Der Editor bearbeitet direkt diese Konfigurationsdatei. Hierfür muss die Konfigurationsdatei für den Webserver Prozess (oder alle Prozesse) beschreibar sein.
Die Konfiguration ist XML formatiert und kann von fortgeschrittenen Anwendern auch direkt bearbeitet werden.

folgende Änderung

Je nach Installationsart befinden sich der CometVisu-Verzeichnisbaum unter

- /var/www/visu… (bei manueller Installation)
- /usr/share/openhab/webapps/visu… (bei automatisierter Installation via apt-get)
- /opt/openhab/www/visu… (bei manueller Installation)
- …

und die eigentliche Konfigurationsdatei „visu_config.xml“ dann im jeweiligen Unterverzeichnis …/visu/config. Mit dieser Konfigurationsdatei im XML-Format wird gearbeitet. Dies kann entweder mit einem textbasierten Editor oder mit dem grafischen Editor erfolgen. Die Verwendung des grafischen Editors setzt jedoch voraus, daß die Konfigurationsdatei entsprechend in die Struktur eines php-fähigen Webservers (z.B. apache oder lighttdp) eingebunden und beschreibar ist. Im Normalfall wird der Webserver über Port 80 angesprochen.

Wird openHAB als backend für die CometVisu eingesetzt, müssen sich die CometVisu-Dateien im openHAB-Verzeichnisbaum befinden. Der openHAB-eigene Webserver wird in der default-Einstellung über Port 8080 angesprochen und ist nicht php-fähig. In diesem Fall muß man sich mit einem texbasierten Editor begnügen oder „apache / lighttdp umlenken“.

Wird openHAB2 als backend für die CometVisu eingesetzt, …..

zur Diskussion vorschlagen wollte, finde ich das wo in github?