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
Python Code dokumentieren
-
- Python-Forum Veteran
- Beiträge: 16025
- Registriert: Freitag 20. Juni 2003, 16:30
- Kontaktdaten:
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.
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.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
-
- User
- Beiträge: 11
- Registriert: Mittwoch 8. Oktober 2008, 08:23
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
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
-
- Python-Forum Veteran
- Beiträge: 16025
- Registriert: Freitag 20. Juni 2003, 16:30
- Kontaktdaten:
Dann hast du aber ziemlich schlecht geschaut, die ersten drei (!) Programme die ich genannt habe nutzen Docstrings zur Dokumentation.Florian F. hat geschrieben:ich habe das grade mal überflogen und kann es sein das ich die Dokumentation extra nochmal machen muss ?
Ich finde so freestanding-Dokumentation in der Regel sinnvoller als automatisch generierte JavaDoc-Style Dokumentation, aber natürlich ist das auch aufwendiger.Florian F. hat geschrieben:Welches wäre deiner meinung nach am sinnvollsten ?
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
@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.
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.
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.
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.
Das schicke bei Python ist, dass man auch zur Laufzeit an die Dokumentation kommt. Wenn man etwa so etwasschreibt:
dann kann man sich auch selbst eine Dokumentation erzeugen - die Funktion `help()` macht es nicht viel anders:
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
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)
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__
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