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.

[peuter]

Wenn man hier jetzt noch kennzeichnen würde, welche Elemente optional sind und welche zwingend benötigt werden, dann wäre das perfekt.

Ist drin, diese werden mit * hinter dem Namen markiert.

Die Parametersätze der Childelemente müssen für mich nicht unbedinft auf die Seite (ansonsten muss das ja zigfach gepflegt werden).

Die Tabelle und Bilder die Du unter: http://test.cometvisu.org/CometVisu/...#einstellungen
siehst, werden voll-automatisch aus der Schema-Datei generiert. Muss man also garnix pflegen, das ist ja da Tolle daran.
An die entsprechende Stelle in der Dokumentation schreibt man einfach:

.. elements_information:: switch

Und dann bastelt er sich das beim Erzeugen der HTML-Seiten der Doku selbst zusammen, dadurch fließen sämtliche Änderungen an der Schema Datei auch direkt mit in die Doku ein und wir sind an der Stelle immer aktuell.

Ich hab das gestern nochmal versucht zu verbessert. Es ist jetzt zumindest vollständig, aber das Label-Element fällt ein wenig aus dem Rahmen,weil es keine eigenen Attribute hat. Ist also immer noch nicht der entgültige Wurf, aber ein weiterer Schritt dorthin.

[SirTobiIV]

Hallo Wurschtel

Den "Aufbau" bzw. das was peuter mit Strukturübersicht meint finde ich auch ne super Idee. Wenn man hier jetzt noch kennzeichnen würde, welche Elemente optional sind und welche zwingend benötigt werden, dann wäre das perfekt.

Die Parametersätze der Childelemente müssen für mich nicht unbedinft auf die Seite (ansonsten muss das ja zigfach gepflegt werden). Entweder man verlinkt hier auf die entsprechende Wiki-Seite/das Kapitel oder bindet den Inhalt von zentraler Stelle dynamisch ein?

[Wurschtel]

Die "Struktur-Übersicht" und den Text dazu habe ich mir ganz auf die Schnelle mit Durchklicken des switch-Widget im Editor zusammen gebastelt und ist auch sicherlich noch mit Fehlern behaftet.
Ich gehe aber mal davon aus, daß alle Widgets nach der selben Systematik aufgebaut sind. Das heißt, es genügt im Grunde nur eine grundsätzliche Beschreibung an gesonderter Stelle und in den einzelnen widget-Beschreibungen nur die jeweils spezifischen Erklärungen.
Dort wäre dann auch die richtige Stelle, um auf Besonderheiten und Ausnahmen einzugehen. Siehe hier z.B. das m.E. nicht konsistent in die Verschachtelungsebenen eingebaute "#text"-Element.

[Wurschtel]

Ich habe schon in diesem git gespickelt ....

[peuter]

Die "Struktur-Übersicht" aus Deinem PDF gefällt mir. Ich muss es nur hinkriegen, sowas automatisch aus der XSD zu bauen, wird ne Herausforderung und vielleicht nicht haargenauso klappen, aber der aktuelle Stand war sowieso noch nicht fertig. Vor allem das Auslesen der Child-Elemente ist noch nicht vollständig in der aktuellen Doku.

Die grundsätzliche Beschreibung des Switch-Widgets habe ich nochmal überarbeitet (ist noch nicht Teil der Doku, muss erst noch gemerged werden). Das in Kombination mit der verbesserten "Struktur-Übersicht" und ich glaube dann hätten wir schon eine ganz ordentliche Widget Beschreibung beisammen.

Ebenfalls Teil des neuen Pull-Requests ist der Anfang der Beschreibung, wie man am Projekt mitarbeiten kann, also sowohl Entwicklung als auch Dokumentation. Kann man sich als Vorschau schonmal hier anschauen:

https://github.com/peuter/CometVisu/...olab/index.rst

Auch hier fehlt noch einiges aber eigentlich wäre das die erste Stelle an der Ihr mitwirken könntet. Anleitung befolgen und aus eigener Erfahren die Stellen verbessern, mit denen man Probleme hatte. Da ich täglich mit git arbeite, fällt es mit schwer eine Anfänger taugliche Anleitung zur Benutzung zu schreiben. Aber ich hab mein möglichstes versucht.

Und bitte nicht abschrecken lassen, dass liest sich sehr kompliziert und ist sicherlich am Anfang auch äußerst gewöhnungsbedürftig (geht allen so, die anfangen git zu benutzen, ging mir auch so). Wird aber mit der Zeit einfacher und hier wird ja auch geholfen wenn es mal irgendwo hakt.

[Wurschtel]

Ich habe mal versucht, mir den Aufbau des switch-Widgets darzustellen und glaube, daß mit den Begrifflichkeiten noch etwas hin- und hergesprungen wird.
Man möge doch bitte mal das anghängte pdf kommentieren.

[Wurschtel]

Ich sah gerade, du hast nun schon unterschiedliche Schriftypen .... dadurch wird es schon etwas klarer. Aber irgendwie bleibt mein Auge noch hängen ....

[peuter]

Also aus meiner Sicht geht es hier nicht um unterschiedliche Parameter (denn die sind wirklich dieselben) sondern um die 2 Varianten diese zu Bearbeiten: Also einmal manuell im XML ein einmal über den Editor. Also dann man einmal per Screenshot gesehen hat wie das aussieht.

[Wurschtel]

Da müssten wir mal in der Historie suchen, wo der her kommt. Aber ich sehe spontan auch keinen Grund das doppelt zu führen.
Der Editor liest seine möglichen Aktionen direkt aus der XSD, also muss beides immer konsistent und gleich sein.

Konsistenz und Nichtredundanz sind hier genau die Stichworte.
Wenn es sich in der Tat um die selben Parameter handelt, dann sollten sie auch nur einmal aufgeführt werden. Hierdurch sollte sich eine noch übersichtlichere Darstellung einstellen.

[peuter]

So mittlerweile ist das Ganze ins Hauptrepository gewandert und ab sofort sind die aktuellen Stände unter folgenden Links zu finden:

Benutzerhandbuch (deutsch):
http://test.cometvisu.org/CometVisu/de/manual/

Sourcecode-Doku (englisch):
http://test.cometvisu.org/CometVisu/api/

Beides nach wie vor große Baustellen, aber ab jetzt kann eigentlich jeder mitarbeiten. Ich muss nur noch die Zeit finden, eine kurze Einführung zu schreiben, wie man sich an der Dokumentation beteiligen kann (Kurzfassung gibts ja oben schon). Es fehlen aber sicherlich noch Erklärungen zu folgenden Dingen:

1. Eine Einführung in das benutzte RST-Format (https://de.wikipedia.org/wiki/ReStructuredText)
2. Eine Erklärung zur selbstentwickelten RST-Erweiterung mit der man die Widget-Beispiele aus den dann Screenshots gemacht werden (kann man zunächst beim Switch Widget abschauen)
3. Eine Erklärung wir man sich die HTML-Dokumentation inkl. Screenshots lokal selbst generieren kann, denn man möchte ja sehen wie das was man geschrieben hat, dann am Ende in fertig ausschaut und ggf. feinjustieren, bevor man einen Pull-Request erstellt. (Die Kurzfassung auf englisch gibts hier: https://github.com/CometVisu/CometVi....doc/README.md)

Wie zu sehen ist ein paar erklärende Worte fehlen noch, da werden ich wohl ein bischen brauchen bis ich das alles vernünftig zusammengeschrieben habe.

[Chris M.]

Au weia .... die Art und Weise der Bearbeitung sieht ziemlich arg nach sehr sehr kompliziert aus.

Nun, das ist der Weg wie man auch an die aktuellste Entwickler Version kommt und hier Code zurück spielen kann - also der bevorzugte

Es müsste aber auch ganz ohne die Installation von Git funktionieren, rein über die Webseite von GitHub.
Dort wie oben beschrieben einen Fork anlegen, dann dort auf die zu editierende Seite gehen (z.B. https://github.com/CometVisu/CometVi...isu_config.xsd - der eigene Pfad wird leicht anders aussehen!), dort neben Raw / Blame / History auf den Stift klicken und dann die Datei ändern.
Im Anschluss, wie oben beschrieben, über die GitHub Seite einen Pull Request stellen.

Vor der nächsten eigenen Änderung einen Pull von CometVisu ins eigene Repository machen um aktuell zu sein.

Das ist etwas mehr klicken, v.a. wenn man das öfters macht - aber lang nicht so schlimm wie es sich erst mal liest.

Vielleicht noch eben zum Stichwort "Parameter":
Es ist doch so, daß sich die eigentliche Konfiguration durch die "visu_config.xml" definiert wird und der Editor hierbei lediglich ein Hilfswerkzeug zur Erstellung der "visu_config.xml" ist. Ganz gleich ob man nun einen Texteditor oder den "Klick-Editor" zur Bearbeitung der "visu_config.xml" verwendet, das Ergbnis sollte immer gleich sein -
demzufolge auch die Parameter.
Wenn dem so ist, würde ich eines besseren Verständnisses wegen, auf eine Unterscheidung zwischen "Parameter" und "Parameter im Editor" verzichten. Oder habe ich etwas Wesentliches übersehen?

Da müssten wir mal in der Historie suchen, wo der her kommt. Aber ich sehe spontan auch keinen Grund das doppelt zu führen.
Der Editor liest seine möglichen Aktionen direkt aus der XSD, also muss beides immer konsistent und gleich sein.

[Wurschtel]

Au weia .... die Art und Weise der Bearbeitung sieht ziemlich arg nach sehr sehr kompliziert aus.

Vielleicht noch eben zum Stichwort "Parameter":
Es ist doch so, daß sich die eigentliche Konfiguration durch die "visu_config.xml" definiert wird und der Editor hierbei lediglich ein Hilfswerkzeug zur Erstellung der "visu_config.xml" ist. Ganz gleich ob man nun einen Texteditor oder den "Klick-Editor" zur Bearbeitung der "visu_config.xml" verwendet, das Ergbnis sollte immer gleich sein -
demzufolge auch die Parameter.
Wenn dem so ist, würde ich eines besseren Verständnisses wegen, auf eine Unterscheidung zwischen "Parameter" und "Parameter im Editor" verzichten. Oder habe ich etwas Wesentliches übersehen?

[peuter]

Was ist der Grund in dem Doku-Link bei den Widgets zwischen "Parameter" und "Parameter im Editor" zu unterscheiden?

Hab ich einfach so aus dem aktuellen Wiki übernommen. Also kein spezieller Grund.

[peuter]

Wen ich mal die technischen Problemchen, die noch existieren gelöst habe. Stelle ich einen Pull-Request und wenn der germerged wurde, werde ich auch beschreiben wie man sich an der Doku beteiligen kann. Momentan geht das aber noch nicht. Das einzige was momentan schon gemacht werden kann, ist die Dokumentation der einzelnen Elemente in der visu_config.xsd zu vervollständigen. Dadrin ist an einigen Stellen sowas zu finden:

<xsd:annotation>
        <xsd:documentation xml:lang="en">Marks the entry as being the default entry in case of non-existing applicable entries.</xsd:documentation>
        <xsd:documentation xml:lang="de">Markiert den Entry als Standard-Entry für den Fall, dass kein anderer passender Entry gefunden werden kann.</xsd:documentation>
      </xsd:annotation>

An vielen Stellen fehlt das noch,und da sich die Dokumentation hieran bedient, kann das schon mal ergänzt werden.

Die Vorgehensweise dafür (und auch für zukünftige Mitarbeit an der Doku) ist ähnlich wie beim mit entwickeln. Man braucht einen Github-Account, forked das CometVisu Repository, checkt das lokal aus, macht seine Änderungen, commited das und stellt einen Pull Request.

Im Einzelnen wäre das:

1. Anmelden bei github.com
2. auf https://github.com/CometVisu/CometVisu gehen und oben rechts auf "fork" klicken
3. Auf dem lokalen Rechner einen Git-Client installieren (ich kann hier nicht für jeden Client die vorgehendweise beschreiben, daher mache ich das stellvertretend für den Kommandozeilen-Client
4. Dem eigenen Fork clonen mit

   git clone https://github.com/<github-username>/CometVisu

   .
5. Änderungen durchführen
6. Ändungen commiten: z.B. wurde die Datei src/visu_config.xsd geändert, dann folgende Befehle ausführen
   

   	git add src/visu_config.xsd
   	git commit -m "hier beschreiben was man geändert hat (wenn gehts auf englisch)"

7. Wieder auf die github-Seite Deines Forks gehen (also im Browser https://github.com/<github-username>/CometVisu öffnen)
8. Auf "new pull request" klicken, auf der Folgeseite können noch mehr Details zur Änderung geschrieben werden, muss aber nicht.
9. Auf "Create Pull Request" klicken
10. warten bis jemand den Pull Request merged, oder Änderungs/Verbesserungsvorschläge hat

Das wars.