Seite 1 von 1
Python Code dokumentieren
Verfasst: Mittwoch 8. Oktober 2008, 09:16
von Florian F.
Hallo,
ich habe zwar schon gegooglet aber bis jetzt nicht passendes gefunden und hoffe das ihr mir weiterhelfen könnt.
Ich möchte demnächst mit einem Projekt anfangen und will dieses auch dokumentieren. Jedoch nicht nur die Funktionen und welche parameter übergeben werden, sondern auch ein kleines Exemplarisches Beispiel für die verwendung von Funktionen haben... Wenn möglich sollte es dann in HTML oder PDF exportiert werden.
Gibt es da ein Programm für ? oder ähnliches?? Danke
Verfasst: Mittwoch 8. Oktober 2008, 09:31
von Leonidas
Hallo Florian F., willkommen im Forum,
Das was du da machen willst, lässt sich über Docstrings regeln. Die kannst du dann mit PyDoc, EPyDoc, PyDoctor oder ähnlichen Tools in HTML-Dokumentation umwandeln.
Alternativ gibt es Sphinx, mit dem man solche Dokumentation schreiben kann wie Python sie selbst hat, die dann in HTML oder LaTeX (und somit in PDF) exportiert werden kann.
Verfasst: Mittwoch 8. Oktober 2008, 09:59
von Florian F.
Hi Leonidas,
ich habe das grade mal überflogen und kann es sein das ich die Dokumentation extra nochmal machen muss ? Sinnvoll wäre es wenn ich ein Beispiel der Funktion in den Komentarblöcken schreiben kann und es irgendwie ausgelesen wird. Welches wäre deiner meinung nach am sinnvollsten ?
Mfg Flo
Verfasst: Mittwoch 8. Oktober 2008, 10:04
von Leonidas
Florian F. hat geschrieben:ich habe das grade mal überflogen und kann es sein das ich die Dokumentation extra nochmal machen muss ?
Dann hast du aber ziemlich schlecht geschaut, die ersten drei (!) Programme die ich genannt habe nutzen Docstrings zur Dokumentation.
Florian F. hat geschrieben:Welches wäre deiner meinung nach am sinnvollsten ?
Ich finde so freestanding-Dokumentation in der Regel sinnvoller als automatisch generierte JavaDoc-Style Dokumentation, aber natürlich ist das auch aufwendiger.
Verfasst: Mittwoch 8. Oktober 2008, 10:37
von BlackJack
@Florian F.: Die Beispielanwendungen von Funktionen sollte man als Interpreter-Sitzung formatieren, oder halt von dort per "copy'n'paste" übernehmen. Dann kann man mit dem `doctest`-Modul die Beispiele automatisch prüfen lassen. Nichts ist verwirrender als Beispiele in der Dokumentation, die nicht zum Verhalten der Implementierung passen.
Wenn Du *richtig* gut Dokumentieren willst, also die Dokumentation wichtiger, oder zumindest genau so wichtig wie der Quelltext ist, dann ist "literal programming" noch eine Möglichkeit. Für Python gibt's da zum Beispiel
pylit.
Ich persönlich benutze EpyDoc mit reStructuredText als Auszeichnung. Den groben Überblick über die Zusammenhänge kann man im Package- oder Modul-Docstring unterbringen.
Verfasst: Mittwoch 8. Oktober 2008, 11:42
von lunar
Sphinx auch eine Erweiterung, um Docstrings aus Klassen und Modulen zu extrahieren, die z.B. von numpy genutzt wird (z.B. im
Input and Output Abschnitt).
Man kann mit Sphinx also sowohl die Schnittstellen einer Bibliothek automatisch anhand der Docstrings dokumentieren, also auch eigenen Fließtext schreiben, z.B. um Hintergründe zu erläutern oder ausführliche Einführungen in bestimmte Themen zu geben, die im Docstring eher deplaziert wären.
Ein Vorteil an dieser Erweiterung von Sphinx ist imho noch, dass man die Abfolge und die Unterteilung dieser automatisch generierten Dokumentation selbst bestimmen und dadurch einen logischen Aufbau erzeugen kann. So kann man z.B. gut zwischen öffentlichem Interface und Interna trennen, aber trotzdem beides in einer Dokumentation vorhalten. Das ist z.B. mit epydoc nicht möglich.
Ich persönlich halte es eher wie Leonidas. Eine strukturierte Fleißtext-Dokumentation lässt sich meiner Meinung nach leichter lesen als eine automatisch generierte, eher ungeordnete API-Dokumentation ala epydoc. Zumal ich API-Dokumentation in Python eh selten lese und daher eigentlich für überflüssig erachte. Eine Fließtext-Dokumentation dient mir als Einführung und gibt einen Überblick, die Docstrings lese ich dann eh in ipython, wenn ich das Paket ausprobiere.
Verfasst: Mittwoch 8. Oktober 2008, 12:35
von sma
Das schicke bei Python ist, dass man auch zur Laufzeit an die Dokumentation kommt. Wenn man etwa so etwasschreibt:
Code: Alles auswählen
def fib(n):
"""
Berechne die Fibonacci-Zahl für die gegebene Zahl n.
Mache es rekursiv.
Aufruf:
>>> fib(10)
89
"""
return 1 if n < 2 else fib(n - 1) + fib(n - 2)
dann kann man sich auch selbst eine Dokumentation erzeugen - die Funktion `help()` macht es nicht viel anders:
Code: Alles auswählen
def document(f):
varnames = f.func_code.co_varnames[:f.func_code.co_argcount]
print "%s(%s):" % (f.__name__, ", ".join(varnames))
print f.__doc__
Natürlich ist es nicht praktikabel, Code, dessen Dokumentation man haben willst, erst laden zu müssen, doch auch mittels Python-Compiler aus dem abstrakten Syntaxbaum die Doc-Strings zu ziehen, ist (insbesondere bei Python 2.6) einfach und wem die vorhandenen Doc-Tools nicht reichen, der baut sich halt noch eines ;)
Entscheidend ist hier IMHO, Dokumentation und Programmcode zusammmenzuhalten, um die Gefahr, dass das auseinander läuft und somit die Dokumentation wertlos wird, möglichst gering zu halten. Wenn man sich bei der Beschreibung der Funktionen und Methoden an gewisse Konventionen hält, kann man diese dann auch wieder aus den Strings herausparsen und speziell bei der Ausgabe auszeichnen. Javas javadoc-Format ist hier sicherlich das große Vorbild.
Stefan