Bei Sphinx handelt es sich um ein Tool, mit dem sehr schön und schnell Dokumentationen für Python Projekte erstellt werden können.
Einführung
Wer selbst an einem Projekt arbeitet bzw. mitarbeitet, kennt vielleicht das Problem das die Dokumentation meistens viel zu kurz kommt. Sie ist meistens nur sehr kurz oder nur sehr schlecht.
Die Dokumentation ist jedoch bei Projekten an dem mehrere Entwickler arbeiten oder mit dem andere Entwickler arbeiten sollen sehr wichtig.
Diesem Problem versucht das Tool Sphinx Abhilfe zu schaffen. Sphinx ist ein in Python geschriebenes Tool und dient der Dokumentation von Python Projekten. Ursprünglich wurde es für die Dokumentation der Programmiersprache Python selbst entwickelt.
Verwendung
Sphinx ist sehr leicht in der Anwendung, denn es verwendet reStructuredText (ReST) als Auszeichnungssprache. Mit ReST ist es möglich schon in der Rohform leicht lesbare Dokumente zu schreiben. So werden zum Beispiel verschiedenen Textelemente wie folgt gekennzeichnet.
===========
Überschrift
===========
**fett** *italic*
* Eine
* Liste
* von
* Angaben
Ein großer Vorteil von Sphinx ist, dass Quellcode Stücken eingebunden werden können. Durch Syntaxhervorhebung besser lesbar gemacht und kann sogar automatisch getestet werden. Es ist auch möglich ganze Docstrings aus dem Python Quellcode einzubinden. Weiterhin kann eine hierarchisch Struktur der Dokumente aufgebaut werden.
Ausgabe
Sphinx kann aus dem ReST HTML und LaTeX Dokumente erzeugen. Die LaTeX Dokumente können anschließend in PDF oder PostScript umgewandelt werden.
Fazit
Mit Sphinx macht das Schreiben der Dokumentation wesentlich mehr Spaß als mit einem herkömmlichen Schreibprogramm, denn es bietet dem Dokumentationsschreiber an vielen Stellen Funktionen an, die das Schreiben erleichtern.
Links
- Python.org (englisch)
- Sphinx (englisch)
- Beispiele:
- Python Dokumentation (englisch)
- weitere Beispiele (englisch)