Getestet mit:Python 2.7; Python 3
Voraussetzungen:Raspberry Pi mit Raspbian Jessie und Internetverbindung (siehe Schritte 1-7 in der Einfuehrung)
0

Dokumentation eines Raspberry Pi Python Projekts mithilfe von Sphinx und Apidoc

Sphinx ist ein grossartiger Dokumentationsgenerator fuer Python und eine kleine Beispieldokumentation ist schnell erstellt. Das Script Apidoc dient dazu, eine Dokumentation auf Basis der Python Docstrings zu erstellen.

Installiere Sphinx
Installiere Sphinx mit

Download des Beispielprojektss
Gib im Terminal ein

Das Python Script myproject.py in MyProject/MyProjectsieht so aus

mit nichts als einer Beispielfunktion und deren docstring. Die anderen Dateien im Projektverzeichnis werden im Tutorial Standard Python Dateistruktur erklaert.

Erzeuge die Dokumentation mit Apidoc und Sphinx
Apidoc durchsucht automatisch alle Python Scripte nach Docstrings und erzeugt dann zusammen mit Sphinx die Dokumentation dafuer. Gib dazu ein

Dies erzeugt ein Verzeichnis docs/ mit allen Dateien der Dokumentation. Sphinx muss aber wissen, wo es die zu dokumentierenden Scripte findet. Oeffne dazu conf.py mit

Gib unter der Zeile

folgendes ein:

Kompilieren und Ansehen der Dokumentation
Nach Aenderungen an den Scripten oder den Dokumentationsdateien muss die Dokumentation kompiliert werden mit

Jetzt kann der Raspberry Pi mit einem Bildschirm, Maus und Tastatur versehen und die Dokumentation im Browser geoeffnet werden durch die Eingabe der Adresse

Alternativ kann die Dokumentation mit scp auf einen Festrechner kopiert und dort betrachtet werden.

Sphinx documentation for my_function

Sphinx-Documentation fuer my_function

Eine Funktionsbeschreibung manuell hinzufuegen
Neben der automatischen Dokumentation mit Apidoc verwendet Sphinx das ReStructured Text-Format fuer die Dokumentation. Oeffne die Hauptdatei der Dokumentation, index.rst, mit

und fuege ueber der Zeile Contents: diese Beispielfunktion ein:

Nach dem kompilieren mit make html sind die Aenderungen in der Html Dokumentation sichtbar:

Sphinx documentation with manual content

Sphinx-Dokumentation mit manueller Funktionsbeschreibung

Weitere Informationen zum Aufbau der Dokumentation und dem .rst Format gibt es in dem exzellenten Tutorial von Sphinx-doc.

Links
Sphinx Website: http://sphinx-doc.org/
Sphinx Tutorial: http://sphinx-doc.org/tutorial.html
Python Docstrings: http://epydoc.sourceforge.net/docstrings.html
Python Beispielprojekt: http://www.knight-of-pi.org/de/standard-python-projekt-dateistruktur/
Dateitransfer mit SCP: http://www.knight-of-pi.org/de/datentransfer-zwischen-festrechner-und-raspberry-pi-mit-scp/
ReStructured Text Dokumentation: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

Knight of Pi

Johannes Bergs aka Knight of Pi. Diploma in Bioinformatics, some Webdesign and Python coding then. Living in the beautiful city of Vienna.

Kommentar

Time limit is exhausted. Please reload CAPTCHA.