Klassendokumentationstool

[Goswin]

(1)
Ich möchte eine (funktionierende) Python3.1-Anwendung mit rund 10 Modulen und 20 Klassen dokumentieren und hätte dafür gerne eine zusammenfassende Auflistung der (Module, Klassen, Methoden) und deren Abhängigkeiten. Diese Info ist natürlich implizit im Code enthalten, und ich frage mich, ob es vielleicht bereits irgendein Python-Tool gibt, welches die Information aus dem Code zieht und in menschenlesbarer Form zusammenfasst. Gibt es so etwas und wo?

(2)
Gibt es vielleicht ein standardisiertes XML-Format (oder sonstiges Format) um objektorientierte Programmstrukturen zu beschreiben?

[.robert]

Moin

zu 1: Ich bin zwar nicht sicher ob es das beste Tool dafür ist, aber schau dir doch mal pydoc an.

zu 2: UML ist ja eigentlich dafür gedacht (unter anderem).

[ms4py]

zu 1:
a) Sphinx Sehr umfangreich, aber auch mit größerer Einarbeitungszeit: http://sphinx.pocoo.org/ Die Python-Dokumentation ist damit z.B. erstellt.
b) epydoc Wenn du *nur* eine API-Dokumentation benötigst, kommst du damit relativ schnell zum Ziel: http://epydoc.sourceforge.net/

[Goswin]

Zusatzinfo: Die doctrings in meinem Code sind extrem dürftig; es geht mir eigentlich darum, mir selber einen Überblick zu verschaffen, den ich bei zig verschiedenen Varianten und Versionen leicht verliere. Die Anwendung funktioniert zwar, hat aber noch (lange) nicht ihre endgültige Form, und ich möchte mir für diese provisorischen Zwischenversionen eine handgeschriebene ausführliche Doku ersparen.

@.robert:
Ich denke, pydoc basiert auf den docstrings, und wenn diese fehlerhaft sind, dann ist auch das Ergebnis von pydoc fehlerhaft. Und meine pydocs, wo überhaupt vorhanden, sind mit Sicherheit fehlerhaft; ich will sie ja gerade anhand des tatsächlichen Codes hinterfragen und berichtigen!

@ms4py:
Verstehe ich richtig, dass ich für Sphinx meine docstrings in sogenanntem reStructuredText schreiben sollte? Momentan ist das zwar nicht der Fall, aber für die Benutzerversion könnte ich mir so etwas unter Umständen vornehmen! (für meine Python3.1-Programme funktioniert Sphinx ja sowieso noch nicht).
Derzeit brauche ich wohl nur, was du API-Doku nennst, also: Liste mit Namen der Module, Namen der Klassen, Namen der Methoden und Abhängigkeiten (was jede einzelne davon macht, weiß ich selber). Wichtig ist mir, dass sie auf dem Code basieren und nicht etwa auf docstrings. Vielleicht brauche ich nicht einmal Diagramme, sondern nur eine übersichtliche Textdatei.

[cofi]

Verstehe ich richtig, dass ich für Sphinx meine docstrings in sogenanntem reStructuredText schreiben sollte? Momentan ist das zwar nicht der Fall, aber für die Benutzerversion könnte ich mir so etwas unter Umständen vornehmen!

Ich habe autodoc noch nicht benutzt, aber so wie ich das lese, musst du an deinen Docstrings nichts aendern, da Plaintext und somit rST kompatibel, sondern kannst rST-Markup nutzen.

Die ganzen API-Dokumentationstools basieren auf den Docstrings. epydoc sollte aber Stubs generieren, wenn es keinen gibt.

Vielleicht hilft dir auch http://pycallgraph.slowchop.com/, zumindest fuer deine Abhaengigkeiten. Aber ich glaube das ist zu genau.

[lunar]

@Goswin: Ich verstehe nicht genau, was Du wirklich möchtest, verzeih mir also, wenn das Folgende Deine Frage nicht beantwortet.

Wenn Du eine Art automatisierten Grobüberblick z.B. über verwendete Module und enthaltene Klassen möchtest, dann würde ich Sphinx nicht verwenden, sondern irgendeine Art von Reverse-Engineering-Programm, welches Graphen und/oder strukturierte Beschreibungen aus Quelltext extrahieren. Das kann von einem einfachen "grep import" bis hin zu UML-Generatoren gehen. Iirc gibt es bei pylint auch ein Tool namens "pyreverse" (oder ähnlich), welches aus Python-Quelltext UML-Diagramme generiert.

Sphinx ist dagegen kein Programm, um automatisch Diagramme zu erstellen, oder diverse Informationen aus Quelltext zu extrahieren. Zwar kann Sphinx mittels verschiedener Erweiterungen Vererbungsdiagramme und Dokumentation automatisch generieren, die Grundstruktur aber musst Du immer noch selbst festlegen. Sphinx ist für die wirkliche Endfassung der API- oder Endbenutzer-Dokumentation da, für diesen Zweck aber wunderbar geeignet.

Die Frage nach dem "standardisierten Format" ist zu ungenau, und kann auf verschiedenste Weise beantwortet werden, je nachdem, was man unter "objektorientierten Strukturen" versteht. UML-Diagramme sind ebenso ein "standardisiertes Format" zur Beschreibung solcher Strukturen wie z.B. die Docbook-Tags zur Dokumentation von Objekten, beide Formate aber leisten völlig unterschiedliche Dinge.