Sphinx für Einsteiger

Sphinx ist das Dokumentationssystem für Python. Eine Einführung findet man hier.

Da die Erstellung eines Dokumentes etwas Übung braucht, wollen wir uns auf die Erstellung einer API-Dokumentation (Application Programming Interface) beschränken.

Dazu nutzt man den Befehl sphinx-apidoc.

Die Python-Programme liegen in einem Ordner (z.B. mit dem Namen QUELLORDNER) und die Dokumentation soll in einem Dokumentationsordner (z.B. mit dem Namen DOKU) erstellt werden.

Der Befehl sphinx-apidoc -F -H '<Name der Dokumentation>' -A '<Author>' -o <Pfad zum Ordner DOKU> <Pfad zum QUELLORDNER>

erzeugt den Dokumentationsordner und legt darin verschiedene Ordner und Files an (siehe hierzu auch http://scriptsonscripts.blogspot.de/2012/09/quick-sphinx-documentation-for-python.html).

Im File conf.py findet man die Zeile #sys.path.insert(0, os.path.abspath('.')). Die Zeile wird entkommentiert und der Pfad ('.') auf den QUELLORDNER angepasst.

Ist der QUELLORDNER direkt ausserhalb des Dokumentationsordners und darin KEIN Paket enthalten (keine DATEI mit Namen __init__.py), ist der Pfad '../QUELLORDNER' zu wählen, ist ein Paket definiert, dann ist der Pfad '../.' .
Nun kann im Dokumentationsordner mittels make-Befehl die geforderte Dokumentation erstellt werden. Sinnvoll wären make html bzw. make latexpdf.

Damit eine gut lesbare Doku entsteht, müssen die __doc__-Strings der Methoden als reStructuredText (reST) geschrieben werden (siehe http://sphinx-doc.org/rest.html#rst-primer).

- neue Zeilen können mittels einer Leerzeile bzw. \n erzeugt werden.