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