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.

[Wurschtel]

Irgendwie finde ich mich in dieser xsd so gar nicht zurecht. Ab welcher Zeile geht's denn dort mit dem switch-Widget los? Ich finde nur zwei, drei Einträge ... aber noch lange nicht alle, die man in der Doku sieht.

[Chris M.]

Die XSD Lesen geht einfacher als sie zu schreiben
Aber die Annotations hinzufügen, sollte schon noch gehen.

[Wurschtel]

Ich versuche!!!!! gerade, die xsd etwas zu verstehen.

[peuter]

In der Beschreibungs-Spalte steht zur Zeit das was in der XSD als Annotation bei dem Attribut steht. Und die sind, wie Christian bereits in https://knx-user-forum.de/forum/supp...705#post981705 angemerkt hat alles andere als Vollständig.

https://github.com/CometVisu/CometVi...config.xsd#L27

Wobei die Erklärung des Spaltenbasierten Layouts des CometVisu woanders in der Doku ausführlich gemacht werden müsste und an dieser Stelle dann nur referenziert werden. Dann sollte die Information dass man dort einen Dezimalwert einträgt der die Spaltenanzahl für dieses Widget festlegt absolut ausreichend sein.

[Wurschtel]

Die Spalte "Beschreibung" ist absolut ausreichend. In diese würde dann z.B. bei colspan auch gehören, was die Dezimalzahl überhaupt darstellt .... pixel, Anzahl oder ... ?

[Wurschtel]

Ich finde deinen Aufbau suuuuuper!

[peuter]

Hier müßte im Typ dann "string" angegeben werden und in der Beschreibung müßte "beschränkt auf "true" und "false"" stehen

Im Grunde könnte man sich den Typ dann fast sparen, denn irgendwie ist alles ein String. Aber ich verstehe was Du meinst, string, decimal sind Typen, true oder false sind keine Typen. Also ist die Tabelle aus der Sicht inkonsistent. Am besten wäre eine weitere Spalte "Mögliche Werte", aber eigentlich ist dafür kein Platz. Mal sehen, muss ich nochmal drüber nachdenken.

[Wurschtel]

Es ist zu warm .... denken unmöglich!!!!!!

[peuter]

Falls sich jemand mal mit der Dokumentationn eines neuen Widgets beschäftigen möchte, sag einfach hier Bescheid. Ich hab hier ein Script, welches automatisch eine neue Dokumentationsseite für ein Widgets aus einem Template erstellt. Diese Seite müsste man dann nur noch inhaltlich anpassen.

Dieser Generator ist auch Teil der CometVisu, aber man braucht zumindest ein laufendes Python um das zu nutzen. Von daher würde ich auf Zuruf einfach die erzeugten Dateien einchecken, dann muss sich niemand mit dem Script rumschlagen, aber wer das unbedingt möchte kann mit das so nutzen:

.doc/main.py create-widget-skeleton --widget <widget-name>

[Wurschtel]

Ganz schnell zu dem:

Und zur Typ-Deklaration:
Auch boolsche Variablen sind aus XML-Sicht nichts anderes als Strings beschränkt auf die 2 Varianten "true" und "false". Denn das muss man ja schlussendlich in die XML-Datei schreiben.

Das war m.E. bereits der richtige Ansatz:
Hier müßte im Typ dann "string" angegeben werden und in der Beschreibung müßte "beschränkt auf "true" und "false"" stehen

[peuter]

Vielleicht wird das klarer, wenn Du Dir mal diese beiden Dateien anguckst:

Das wäre das was Du schreiben würdest:
https://raw.githubusercontent.com/Co...trum/index.rst

Und dass wird automatisch daraus gebaut:
http://test.cometvisu.org/CometVisu/...rum/index.html

Klar sollten solche Begriffe konsistent genutzt werden. Ich hatte zumindest beim Switch Widget versucht Element und Attribut anstatt Parameter zu nutzen. Wenn da noch inkonsistenzen drin sollten sollten die behoben werden. Wir befinden uns je hier noch in der Anfangphase der neuen Dokumentation, von daher sind da sicherlich noch einige Inkonsistenzen drin.

Und zur Typ-Deklaration:
Auch boolsche Variablen sind aus XML-Sicht nichts anderes als Strings beschränkt auf die 2 Varianten "true" und "false". Denn das muss man ja schlussendlich in die XML-Datei schreiben.

[Chris M.]

Ich bin auch noch am Lernen. Aber sooo schwer ist es nun auch wieder nicht.

Am einfachsten dürfte der Start fallen, wenn Du die visu_config.xsd (https://github.com/CometVisu/CometVi...isu_config.xsd) entsprechend erweiterst. Dort gibt es schon einige <xsd:annotation> Elemente die zeigen, wie es geht. Und überall wo es die noch nicht gibt, kannst Du wunderbar einsteigen und mithelfen.

Das Ergebnis wird dann automatisch in den entsprechenden Tabellen bei der Doku eingebaut (wie z.B. im powerspectrum sichtbar: http://test.cometvisu.org/CometVisu/...rum/index.html)

Solche Doku-Seiten gibt es aktuell aber noch nicht für viele Widgets. D.h. hier kannst Du auch aktiv werden. Hier muss unter /doc/manual/de/config/widgets (https://github.com/CometVisu/CometVi...config/widgets) für jedes Widget ein entsprechendes Unterverzeichnis angelegt werden und dort eine index.rst erstellt werden. Gut Spicken kann man beim Switch-Widget unter https://github.com/CometVisu/CometVi...itch/index.rst - wobei diese Datei schon sehr viele Möglichkeiten zeigt, d.h. man sich davon nicht erschlagen lassen darf

[Wurschtel]

Auch bei der Typ-Deklaration geht es noch etwas inkonsistent zu. string und decimal sind klar, aber die Typen true und false sind doch Boolsche Variablen. Auswahlmöglichkeiten wie read, readwrite usw. wiederum strings ... allerdings auf vorgegebene beschränkt.

[Wurschtel]

Ob es denn wohl auch mal sinnvoll wäre, die Begiffe Widget, Parameter, Element, Attribut und Eigenschaft durchgängig festzulegen? Ich glaube das wird zur Zeit noch etwas individuell gehandhabt.