Python Code dokumentieren

Wenn du dir nicht sicher bist, in welchem der anderen Foren du die Frage stellen sollst, dann bist du hier im Forum für allgemeine Fragen sicher richtig.
Florian F.
User
Beiträge: 11
Registriert: Mittwoch 8. Oktober 2008, 08:23

Python Code dokumentieren

Beitragvon Florian F. » Mittwoch 8. Oktober 2008, 09:16

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
Benutzeravatar
Leonidas
Administrator
Beiträge: 16023
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Beitragvon Leonidas » Mittwoch 8. Oktober 2008, 09:31

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.
My god, it's full of CARs! | Leonidasvoice vs Modvoice
Florian F.
User
Beiträge: 11
Registriert: Mittwoch 8. Oktober 2008, 08:23

Beitragvon Florian F. » Mittwoch 8. Oktober 2008, 09:59

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
Benutzeravatar
Leonidas
Administrator
Beiträge: 16023
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Beitragvon Leonidas » Mittwoch 8. Oktober 2008, 10:04

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.
My god, it's full of CARs! | Leonidasvoice vs Modvoice
BlackJack

Beitragvon BlackJack » Mittwoch 8. Oktober 2008, 10:37

@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.
lunar

Beitragvon lunar » Mittwoch 8. Oktober 2008, 11:42

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.
sma
User
Beiträge: 3018
Registriert: Montag 19. November 2007, 19:57
Wohnort: Kiel

Beitragvon sma » Mittwoch 8. Oktober 2008, 12:35

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

Wer ist online?

Mitglieder in diesem Forum: 0 Mitglieder