quellcode ordentlich dokumentieren

[mnietz]

Hallo Leute,

ich bin auf der Suche nach Kommentarstandards in Python. Bin über die DocStrings gestolpert und wollte mal Fragen ob es irgendwo ein kleines Benimm-Regel-Werk speziell für Python gibt.

Danke,

Matthias.

[Milan]

hmm... gibts bestimmt, nur kenn ich keins direkt. kommentieren kann man auf verschiedene Weisen:

Code: Alles auswählen

#das ist ein normaler kommentar, eingelietet von der Raute
def bla(x):
    """returns 2*x"""
    return 2*x
#in bla.__doc__ steckt jetzt der docstring "returns 2*x"

aber ein Stilregelwerk hab ich selber keins gefunden, ich benutz einfach diese zwei Möglichkeiten, wo ich es brauche.

[mnietz]

Hallo auch,

ja auf diese Kommentarmöglichkeiten bin ich auch schon gestossen, aber es gibt doch bestimmt auch Werkzeuge um eine Dokumentation in html o.ä. erstellen zu lassen, die eine best. Dokumentations-Syntax bedingt, oder?

Nur find ich grad nichts dazu :(

Gruß,

Matthias

[Dookie]

Hallo,

Hier ein paar Links
http://www.pythonwiki.de/DocString
http://www.python.org/doc/current/lib/module-pydoc.html
http://epydoc.sourceforge.net/stdlib/pu ... odule.html

Gruß

Dookie

[Dookie]

Nachtrag:

ich habe gerade, unter Linux, in der Console

Code: Alles auswählen

pydoc -w sys

getestet. Es wurde damit ein HTML-Dokument "sys.html" erzeugt

Ansonst schau Dir die Sources zu verschiedenen Modulen,
die bei Python dabei sind an und mach deine Docstrings entsprechend.

Bei Docstrings am besten auf Umlaute verzichten oder sie gleich in HTML-Form schreiben. Oder gleich auf englisch dokumentieren.


Gruß

Dookie

[mnietz]

Hi, ja das mit pydoc- w file ist eine coole Sache, und das mit dem Kommentieren sollte jetzt auch klappen.

Vielleicht ne dumme Frage, aber muss ich eigentlich immer die pydoc.py in dem Verzeichnis haben wo die Quelldatei liegt für die eine Doku generiert werden soll?
Ich arbeite hier unter windows und das kennt Pfade ja nur zu ausführbaren Programmen (und pydoc muss ich dann ja auch erst mit "python pydoc.py -w file" starten) oder hilft da nix?


Gruss,

Matthias

[Dookie]

puh, wie das mit Windows läuft, hab ich keine Ahnung, benutze nur Linux. Allerdings gibts bei Pydoc auch ein grafisches Frontend mit Tkinter, das zumindest unter Linux die html-doku direkt an einen Browser schicken kann.
Falls das mit Windows ned geht, schau die doch mal http://www.knoppix.de an. Da kannst Du mal in Linux reinschnuppern und wenns gefällt leich ein Debiansystem draus machen.

Gruß

Dookie

[Voges]

Hallo!

Ist ja wirklich nett das Tool. Schön bunt

Vielleicht ne dumme Frage, aber muss ich eigentlich immer die pydoc.py in dem Verzeichnis haben wo die Quelldatei liegt für die eine Doku generiert werden soll?

Du könntest den Aufruf in eine Batchdatei (z.B. "pydoc.bat") schreiben und die Batchdatei selbst in einen Ordner packen, der über die Path-Umgebungsvariable erreichbar ist. Inhalt der Batchdatei:

Code: Alles auswählen

C:\Python22\python.exe C:\Python22\Lib\pydoc.py %1 %2 %3 %4 %5 %6 %7 %8 %9

Der Aufruf erfolgt dann mit ...
pydoc.bat -w .\myScript.py

Jan

[mnietz]

Gute Idee,

so wird in Zukunft gemacht!

Gruß,
Matthias

[EdiRitter]

Hallo,

ich habe auch noch eine Frage zu pydoc.

Für die Datei 'dwGUI.py' erstelle ich mit pydoc die 'dwGUI.html'.
Im rechten oberen Eck, gibt's etwas schönes: Index.

Ich habe eigentlich nur 2 Dateien: Ich hätte zu den Files 'dwGUI.html' und 'dwApp.html' ein schönes Indexfile. Könnt ihr mir sagen wie das geht?

MfG

[Dookie]

Hi EdiRitter,

hmm wenn ich dich richtig verstehe, würde ich ein Package machen mit den beiden Pythondateien.
Dazu legst du die beiden Scripte in ein Verzeichnis und machst noch eine Datei __init__.py, die ruhig leer sein kann, hinein.
Für dieses Package pydoc -w Verzeichnisname aufrufen.


Gruß

Dookie

[Leonidas]

Es gibt auch einen Standard für die Kommentare: reST, der sich auch gut zum allgemeinen Dokumentieren eignet.

Auch doctest könntest du dir mal anschauen.

[EdiRitter]

Hallo,

ich bekomme folgende Fehlermeldung:

no Python documentation found for 'dwApp'

Woran könnte es liegen? Ich habe diesen Vorschlag ausprobiert:

Dazu legst du die beiden Scripte in ein Verzeichnis und machst noch eine Datei __init__.py, die ruhig leer sein kann, hinein.
Für dieses Package pydoc -w Verzeichnisname aufrufen.

Eddy

[flyingfish]

Hallo Leute,

auf eddis frage haette ich auch gerne eine Antwort, die gleiche Meldung bekomme ich naemlich auch.

gruesse und vielen dank,

flyingfish

[Leonidas]

Also gut:
Ich habe einfach mal einen Ordner edoc erstellt. Darin habe ich eine __init__.py erstellt. Daneben habe ich meine anderen, zu dokumentierenden Quellcodes reinkopiert. Dann bin ich in den Ordner drüber gegangen und habe pydoc -w edoc\\ ausfgeführt. Das hat mir dann die HTML Dateien produziert.

[flyingfish]

ah, irgendwie geht es bei mir jetzt auch, weiss nicht wieso vorher nicht.
Allerdings generiert er auch nur die index datei "project.html". Er gibt dort die darunterliegenden Dateien an, verlinkt sie aber mit project.dateiname.html.
Die existieren jedoch nicht, da er sie nicht generiert hat. Aber ich kann ja in das verzeichnis gehen, die dokumente generieren und ein rename bekomme ich ja noch hin

Danke schoen!

[jens]

Genau das selbe Problem hab ich nun auch...

Es kann doch aber nicht nur so geregelt sein, das man jede Datei einzeln erstellen muß...

OK, man könnte schnell mit os.walk() das erledigen, aber es muß doch auch schon andere auf die Idee gekommen sein...

Die HTML-Ausgaben von pydoc sind ja schon ganz nett. Schöner wäre es allerdings wenn man daraus direkt verlinkt zum Quellencode der jeweiligen Funktionen/Methoden/Klassen hin und her wechseln könnte...

EDIT: Hab das http://www.python.org/moin/DocumentationTools gefunde...

[jens]

epydoc ist ganz nett... Es generiert sowas: http://epydoc.sourceforge.net/api/
Ich würde es allerdings nett finden, wenn man aus den generierten DOC direkt in den Quellencode springen könnte...

Um Quellencode als HTML zu konvertieren, gibt es ein ganz nützlichen Eintrag im Cookbook: http://aspn.activestate.com/ASPN/Cookbo ... cipe/52298

Kennt jemand schon dafür ein fertiges System?