Eine neue Scripter API Dokumentation
Verfasst: Sa 15. Aug 2020, 11:39
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 !
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 !
