Sphinx und FileMaker – Python basierte Automation professioneller Software Dokumentation
Sphinx Dokumentation in FileMaker Pro
ACSR entwickelt regelmäßig Desktop GUI Frontends, die sowohl unter MacOSX als auch unter Windows zur Anwendung kommen. Dabei kommt u.a. die kommerzielle Rapid Development Datenbank FileMaker Pro zum Einsatz.
FileMaker Pro bietet auch in der Advanced Edition für Entwickler keine spezielle Lösung zur Erstellung von Inline Dokumentationen an. Obwohl im Prinzip Dokumentationen direkt in FileMaker erstellt werden können, hat die externe Verwaltung ein paar entscheidende Vorteile.
ACSR hat den in Python geschriebenen Sphinx Documentation-Builder in FileMaker Pro integriert. Sphinx ist wegen des universellen Ansatzes nicht nur für Python Projekte geeignet. Die Entwicklungsumgebung ist im Moment nur unter Mac OS X im Einsatz, das bereits mit installiertem Python daherkommt. Die Umgebung sollte aber auch problemlos unter Windows installierbar sein.
Was macht Sphinx?
-
Die Dokumentation wird als einfache Textfiles mit minimalem Markup (restructuredText Markup) erstellt.
- Die Dokumentation kann übersichtlich aus mehreren hierarchisch gegliederten Dokumenten aufgebaut werden.
- Der Source Text kann in SVN oder GIT versionsverwaltet werden.
-
Die Entwicklungsumgebung mit installiertem Python ist nur für den Entwickler nötig. Die Dokumentation selbst läuft ohne Plugin auch unter Windows.
-
In der Dokumentation können ToDos eingestreut werden und in der Ausgabe nach Wahl unterdrückt werden.
-
Die Dokumentation kann mit Logo und eigenem Design versehen werden.
-
Sowohl “Internetausdrucker” als auch die Mobilfraktion kommen durch weitere Ausgabeformate auf ihre Kosten.
- Auf Knopfdruck wird eine sauber durchformatierte PDF Dokumentation mit Index, Querverweisen, Inhalt etc. generiert (via LaTeX, ohne mit LaTeX selbst in Berührung zu kommen).
- Als Format für Mobilgeräte steht ePub (eBook) zur Verfügung.
- Es stehen weitere Ausgabeformate zur Verfügung bzw. können implementiert werden.
Das Ergebnis in Filemaker
- Per Menübefehl oder Script mit Parameter steht via Webviewer eine kontextsensitive Dokumentation direkt in Filemaker zur Verfügung.
- Wahlweise kann die Dokumentation auch im Browser angezeigt werden.
- Mit den neuen fmscript:// URL Schema ab FM12 kann man im Desktop Client aus der Dokumentation sofort Aktionen starten! (bisher nur FMGo)
- Die Dokumentation kann sehr einfach außerhalb von FileMaker auf einem Webserver gehostet werden.
Das System läuft im aktuellen Zustand schon hervorragend und hat sich bereits bei der täglichen Arbeit im Team bewährt!
Ausblick
Nächster geplanter Entwicklungs Schritt ist ein Filter, um direkt aus den Kommentaren in Filemaker Scripten eine sauber durchformatierte Dokumentation zu generieren.