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

Donnerstag 6. März 2003, 17:12

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

Donnerstag 6. März 2003, 18:05

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

Donnerstag 6. März 2003, 18:14

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:

Donnerstag 6. März 2003, 18:52

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

Freitag 7. März 2003, 10:33

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:

Freitag 7. März 2003, 14:46

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

Freitag 7. März 2003, 15:06

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

Freitag 7. März 2003, 18:51

Gute Idee,

so wird in Zukunft gemacht!

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

Mittwoch 5. Januar 2005, 22:16

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:

Donnerstag 6. Januar 2005, 00:03

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

Donnerstag 6. Januar 2005, 08:35

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 Modvoice
EdiRitter
User
Beiträge: 27
Registriert: Dienstag 19. Oktober 2004, 19:47
Wohnort: Germany

Sonntag 9. Januar 2005, 20:36

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

Mittwoch 23. März 2005, 12:12

Hallo Leute,

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

gruesse und vielen dank,

flyingfish
Leonidas
Administrator
Beiträge: 16024
Registriert: Freitag 20. Juni 2003, 16:30
Kontaktdaten:

Mittwoch 23. März 2005, 12:30

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 Modvoice
Antworten