quellcode ordentlich 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.
Antworten
mnietz
User
Beiträge: 14
Registriert: Mittwoch 5. März 2003, 11:06
Wohnort: Berlin

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
User
Beiträge: 1078
Registriert: Mittwoch 16. Oktober 2002, 20:52

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
User
Beiträge: 14
Registriert: Mittwoch 5. März 2003, 11:06
Wohnort: Berlin

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
Python-Forum Veteran
Beiträge: 2010
Registriert: Freitag 11. Oktober 2002, 18:00
Wohnort: Salzburg
Kontaktdaten:

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 8)

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
User
Beiträge: 14
Registriert: Mittwoch 5. März 2003, 11:06
Wohnort: Berlin

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
Python-Forum Veteran
Beiträge: 2010
Registriert: Freitag 11. Oktober 2002, 18:00
Wohnort: Salzburg
Kontaktdaten:

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
User
Beiträge: 564
Registriert: Dienstag 6. August 2002, 14:52
Wohnort: Region Hannover

Hallo!

Ist ja wirklich nett das Tool. Schön bunt :-)
mnietz hat geschrieben: 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
User
Beiträge: 14
Registriert: Mittwoch 5. März 2003, 11:06
Wohnort: Berlin

Gute Idee,

so wird in Zukunft gemacht!

Gruß,
Matthias
EdiRitter
User
Beiträge: 27
Registriert: Dienstag 19. Oktober 2004, 19:47
Wohnort: Germany

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
Python-Forum Veteran
Beiträge: 2010
Registriert: Freitag 11. Oktober 2002, 18:00
Wohnort: Salzburg
Kontaktdaten:

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
[code]#!/usr/bin/env python
import this[/code]
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

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.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
EdiRitter
User
Beiträge: 27
Registriert: Dienstag 19. Oktober 2004, 19:47
Wohnort: Germany

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
User
Beiträge: 33
Registriert: Sonntag 23. Januar 2005, 23:36

Hallo Leute,

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

gruesse und vielen dank,

flyingfish
Leonidas
Python-Forum Veteran
Beiträge: 16025
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

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.
My god, it's full of CARs! | Leonidasvoice vs (former) Modvoice
flyingfish
User
Beiträge: 33
Registriert: Sonntag 23. Januar 2005, 23:36

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!
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

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

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
Benutzeravatar
jens
Python-Forum Veteran
Beiträge: 8502
Registriert: Dienstag 10. August 2004, 09:40
Wohnort: duisburg
Kontaktdaten:

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?

GitHub | Open HUB | Xing | Linked in
Bitcoins to: 1JEgSQepxGjdprNedC9tXQWLpS424AL8cd
Antworten