API documentation overview / explanation for both pygtk 3 and pygtk 4

[rubyFeedback]

(First, I would like to apologize for writing the next part in viennese slang, but it feels more "localized" when doing so. For those not understanding German, the gist of my issue request here is a "top-level explanation" for pygobject in regards to the API documentation, available at https://lazka.github.io/pgi-docs/Gtk-3.0/ and https://lazka.github.io/pgi-docs/Gtk-4.0/, for instance - or, rather, at https://lazka.github.io/pgi-docs/.)

Sers Christoph,

Du, respektive ihr, sofern es sich um ein Team handelt, macht ja API Dokumentation zu python und GTK verfügbar.

Zuerst habe ich von dem Projekt über gtk3 gehört, eben:

https://lazka.github.io/pgi-docs/Gtk-3.0/

Vor 1-2 Jahren oder so war die Dokumentation zu Gtk-4.0 entweder nicht vorhanden, oder nur sehr spärlich gegeben,
sofern ich mich richtig erinnere. Dies scheint sich ja langsam zu ändern - so gibt es ja nun:

https://lazka.github.io/pgi-docs/Gtk-4.0/

Oder ich habe es zuvor nicht gesehen.

Die API Dokumentation ist sehr hilfreich. Ich verwende auch Python, wobei ich jedoch tendenziell
eher Ruby verwende. Jedoch ist python code eigentlich ruby code extrem ähnlich (in gewisser Art und
Weise), so das ich kaum Schwierigkeiten habe zwischen den beiden Programmiersprachen zu wechseln. Und
hier verwendete ich natürlich auch die API Dokumentation von den pgi-docs (eben die URLs oben). Auch für
ruby-gtk4 würde ich gerne die hervorragende Dokumentation auf https://lazka.github.io/pgi-docs/
verwenden. Dies hat mir bereits extrem bei ruby-gtk4 geholfen; ruby leidet ja leider oft unter einer
schlechten Qualität an Dokumentation, zum Teil da viele japanische Entwickler die englische Sprache
nicht so gut beherrschen.

Nun zu der Frage, wieso ich hier einen issue request mache.

Du, respektive ihr, verwendet ja FAQ entries hier:

https://lazka.github.io/pgi-docs/#faq.html

Es gibt hier nun jedoch ein paar Fragen die ich mir stelle, die von der FAQ aktuell nicht beantwortet
werden; respektive fehlt mir ein wenig die Übersicht, aka "introduction" oder so.

Daher zuerst einmal mein erster Vorschlag:

1. Wäre es möglich eine Art Überblick zu geben?

Also auf:

https://lazka.github.io/pgi-docs/

Wäre es eventuell hilfreich wenn man so etwas wie "Introduction" oder "About" oder
"About the project" sagen könnte. Das muss nicht besonders umfangreich sein,
aber könnte erklären wieso das Projekt existiert, welche Personen aktuell daran
mitwirken (wenn es ein Team-Projekt ist), welche Ziele das Projekt hat: eben solche
Dinge. Auch wie man mitwirken kann vielleicht, obwohl das eventuell in die FAQ
aufgenommen werden kann. Zum Beispiel ob man auch konkrete Beispiele
geben kann, die integriert werden könnten. Solche Dinge.

2. Für die FAQ selbst, abgesehen von 1), hätte ich folgende Fragen; Ich fasse die
   in diesem Punkt zusammen. Müssen natürlich nicht alle in der FAQ aufscheinen,
   aber wenn du sie als informativ erachtest können die natürlich direkt in
   die FAQ reingestellt werden.

Wie wird die API Dokumentation erstellt? Also, nur die einzelnen Schritte
von (vermutlich) statischen Dateien hin zu der offiziellen API Dokumentation?

Wie wird neue Information hinzugefügt, i. e. wer zum Beispiel fügt Beispiele
für python-gtk4 hinzu? Als ich zuletzt nach python-gtk4 Beispielen gesucht
habe, über Google, hab ich nur sehr wenig gefunden; für python-gtk3 hingegen
extreml viel. Dies hilft mir insofern als da ich viele Beispiele in ein ruby gem
gegeben haben (nachdem ich es zu ruby konvertiert habe) und dies auch auf
rubygems.org online gestellt habe. Ich kann somit quasi pgi-docgen "abklappern"
nach Beispielen, auch nach Referenz, und füge dann Informationen hinzu
in dieses Ruby Projekt. Hoffe das erklärt ein wenig meine Motivation wieso
ich dies hier als issue request reingestellt habe. Wenn das zu viel Aufwand ist,
kein Problem - eventuell reichen ein oder zwei Sätze und dann kann das hier
einfach geschlossen werden; Zeit ist ein stark limitierter Faktor.

So oder so möchte ich mich für pgi-docgen bedanken, denn es ist wirklich
meiner Meinung nach viel brauchbarer als die offizielle Dokumentation
zu GTK3 aber auch GTK4. Insbesondere bei den Änderungen von GTK4
verstehe ich oft nicht was sich da geändert hat; bei GTK4 habe ich einfach
von den Python Beispielen stibitzt, aber das geht ja nur wenn man dementsprechend
auch Beispiele finden kann. Ich werde dann wohl im neuen Jahr erneut nach
Python + GTK4 Beispielen suchen - hoffe das sich das alles verbessert im
kommenden Jahr.

Guten Rutsch und Grüße aus dem fernen Osten (Wien).

[lazka]

Hey,

dieses Projekt ist leider seit mehreren Jahren nicht mehr all zu gut gewartet und wenn ich Zeit rein stecke, dann nur um es am Leben zu erhalten.

Da die Doku aus dem Quellcode auto-generatiert wird ist jede Art von Library-spezifischer Verbesserung schwierig. Von daher wird die Doku wahrscheinlich immer aus mehreren Seiten mit unterschiedlichen Prioritäten bestehen (pygobject, gtk, api-docs)..

Auf gitlab gibt es ein aktuelles Thema bezüglich Verbesserungen: https://gitlab.gnome.org/GNOME/pygobject/-/issues/609

Grüße aus Graz