Eine neue Scripter API Dokumentation

Antworten
Benutzeravatar
a.l.e
Beiträge: 730
Registriert: Di 3. Feb 2015, 12:56

Eine neue Scripter API Dokumentation

Beitrag von a.l.e »

Hier gibt's auch ein paar Script Kiddies (hi Julius!) und deshalb eine (automatisch übersetzte) Kopie meiner Ankündigung (die im Scribus-Forum nicht veröffentlicht wurde, weil dort alles kaputt).

Immer wieder habe ich Beschwerden über die Scripter-Dokumentation erhalten (unter anderem natürlich!).

Da die Scribus-Dokumentation nicht wirklich frei ist, gibt es nicht viel, was ich tun wollte / konnte.

Letzte Woche bekam ich eine weitere kritische Stimme zur API-Dokumentation, und ich habe beschlossen, dass es an der Zeit ist, zu prüfen, ob es möglich ist, etwas Vernünftiges zu erstellen, indem man die API aus den docstrings exportiert.

Der Ausgangspunkt war das " gute alte"

https://github.com/aoloe/scribus-script ... api-doc.py

das Endergebnis lautet

https://github.com/aoloe/scribus-script ... ripter-api

die zur Erstellung von

http://impagina.org/scribus-scripter-api/

verwendet werden kann. (ja, die Leute haben auch darum gebeten, die API-Hilfe im Web zu veröffentlichen)

Yeah, keine undokumentierten Befehle mehr!
Nur noch eine Stelle, wo der Befehl dokumentiert wird!

Das Endziel ist, die redigierte API-Hilfe in der Scribus-Hilfe durch einen separaten Hilfeeintrag zu ersetzen (der gezieltere Suchergebnisse liefert).

Falls du Vorschläge zur Verbesserung des Skripts oder der Ausgabe hast, kannst du sie gerne hier oder im Bugtracker kommentieren

https://bugs.scribus.net/view.php?id=16213

oder im oben verlinkten scribus-script-repository Github-Repository.

Für diejenigen, die bereit sind zu helfen, könnte ich eine Hand für die Verbesserung von den docstrings brauchen:

- alle Signaturen in den docstrings so anpassen, dass sie den echten Python-Signaturen entsprechen ("getAllObjects(page: int=None) -> list" anstelle von "getAllObjects(["page"]) -> list".
- die Formatierungen korrigieren, wenn sie sich nicht gut in Markdown/HTML konvertieren lassen (wie Codeschnipsel und Listen)
- eine einheitliche Kennzeichnung von deprecated Funktionen
- Namensänderungen für Funktionen vorschlagen (und implementieren), wenn diese nicht dem allgemeinen Namensschema entsprechen.
- allgemeine Verbesserungen von der Dokumentation in den docstrings.

Ciao
a.l.e
p.s.: danke DeepL.com/Translator !
Benutzeravatar
Anke
Beiträge: 888
Registriert: Sa 31. Jan 2015, 09:01

Re: Eine neue Scripter API Dokumentation

Beitrag von Anke »

Hallo a.l.e,
ich finde es super, dass du diese Dokumentation zur Verfügung stellst. :danke:

Ich habe leider absolut keine Ahnung von python, java oder ähnliches. Aber ich bin froh, dass es nun für alle Scripter/-innen so eine Anlaufstelle gibt. Ich hoffe du bekommst ganz viel Hilfe bei dem Projekt.

Viele Grüße
Anke
Wer glaubt, dass Administratoren administrieren
und Moderatoren moderieren
Glaubt auch, dass Zitronenfalter Zitronen falten
Bild
Antworten