Vorschlag für Verbesserungen der Dokumentation

[Wurschtel]

Mir ist immer noch nicht so ganz klar, wie man Beiträge zur Dokumentation erstellt und diese formatiert. Auch sehe ich noch nicht so wirklich, wo der Automatismus endet und die manuelle Eingabe beginnt. Irgendwie wird da ja auf eine xsd-Datei zurückgegriffen.

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

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

[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

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

[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]

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]

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

[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]

Ich finde deinen Aufbau suuuuuper!

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

[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]

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

[Chris M.]

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

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