Eine Dokumentation schreiben

[pixewakb]

Hallo zusammen,

ich habe inzwischen einige Module geschrieben und einige Klassen und Funktionen darinnen. Langsam reduziere ich die Gesamtzahl der Tools und entwickle manche Sachen weiter, jedenfalls kann ich häufig mal gut eine Dokumentation zu meinen Programmen gebrauchen, weil einiges inzwischen lang und umfangreich geworden ist und ich nicht mehr alles täglich nutze oder zumindest nicht immer in den Quelltext schauen muss, weil manche Sachen nur noch gestartet werden müssen.

Meine Frage ist, ob es sinnvolle Standards gibt, ein Modul zu dokumentieren?

Ich habe mir ein Klassendiagramm je Klasse geschrieben und dann alle Attribute und alle Methoden notiert und eine kurze Erklärung ergänzt, also z. B. so etwas:

Klasse: Report

Die Klasse modelliert einen Bericht, der auf die Platte geschrieben werden kann.

== Attribute ==

PATH
::Pfad zum Speicherort

== Methoden ==

set_PATH()
::Legt den Speicherort fest und erwartet einen Pfad als String.

Gibt es einfache, überschaubare Anleitungen und vor allem eingängige Standards, wie solche Anleitungen auszusehen haben? Ich hätte auch keine Probleme damit Standards für z. B. Java zu nutzen, wenn die z. B. eingängig, schnell und einfach zu erlernen sind. Obiges Beispiel orientiert sich an einer Dokumentation, die ich mal für ein sehr einfaches Java-Programm gesehen habe.

Konkrete Frage: Gibt es eine gängige Variante, wie ich die Parameter einer Methode mitangebe? Ich habe gesehen, dass Python in der offiziellen Dokumentation gerne etwas der Form:

report.set_PATH(...)
::Erklärung

macht. Mein Problem ist, dass ich mich nicht erst in eine eigene Software dafür einarbeiten möchte (und kann), d. h. SPHYNX kenne ich dem Namen nach, aber das ist nicht Kerninteresse. Ich nutze zur Dokumentation usw. ein Wiki, wo ich auch die Anleitungen rein schreiben kann. Jemand einen Tipp, wie z. B. eine sinnvolle Dokumentation aussehen könnte!?

[cofi]

Der sinnvolle Standard sind Docstrings, am besten eben fuer Sphinx aufbereitet, d.h. wenn Argumente und Rueckgabewerte dokumentiert werden eben mit entsprechendem Markup.

[pixewakb]

Der Vollständigkeit halber (falls es später mal jemand sucht), der Link:

sphinx-doc.org

Das erscheint mir persönlich immer noch nach sehr viel Overhead. Ich sehe zwar im Moment, dass ich Kommentare sowohl in das Skript, als auch ins Wiki packe, aber persönlich würde ich für mich tendenziell immer noch eine simplere Herangehensweise suchen.

[DasIch]

Meine Frage ist, ob es sinnvolle Standards gibt, ein Modul zu dokumentieren?

Es gibt einen: Sphinx. Etwas anderes zu nutzen ist ein gewaltiger Fehler es sei den du kannst begründen wieso dein Projekt so speziell ist, dass in diesem Fall eine andere Lösung eine bessere Dokumentation produziert.

[pixewakb]

Ich habe bei Sphynx noch keinen leichten Einstieg gefunden. Das Wiki habe ich eh installiert und ersetzt für meine Belange auch die Versionsverwaltung, d. h. ich speichere dort meinen Quellcode.

Ich habe vor einiger Zeit mal einen Bugtracker aufgespielt, war begeistert, um dann festzustellen, dass ich mit einer separaten Seite im Wiki, was ich eh schon habe, besser fahre. Ich habe sorge, dass die ich die x.-Software habe, mich einarbeite und am Ende feststelle, dass ich mich verzettle.

Im Fokus steht ganz klar das Lösen von Problemen mit Python und nicht die Entwicklung überzeugender Python-Software mit vorzeigbarer Dokumentation. Die Software bekommt wahrscheinlich eh niemand zu Gesicht und ist zu schlecht programmiert (, d. h. ungelenk geschrieben, aber erfüllt ihren Zweck).

Ich sehe bei Sphynx nur die Möglichkeit HTML oder PDF auszugeben, nicht aber Wiki-Syntax. Ich habe auf Anhieb noch keine Beispielseite gefunden, wo es mir erklärt wird, wie ein Docstring bei einer Funktion usw. aussehen müsste.

[DasIch]

Das Wiki habe ich eh installiert und ersetzt für meine Belange auch die Versionsverwaltung, d. h. ich speichere dort meinen Quellcode.

Das ist doch wohl hoffentlich ein Scherz.

Ich habe vor einiger Zeit mal einen Bugtracker aufgespielt, war begeistert, um dann festzustellen, dass ich mit einer separaten Seite im Wiki, was ich eh schon habe, besser fahre. Ich habe sorge, dass die ich die x.-Software habe, mich einarbeite und am Ende feststelle, dass ich mich verzettle.

Bitte sag dass das ein Scherz ist.

Im Fokus steht ganz klar das Lösen von Problemen mit Python und nicht die Entwicklung überzeugender Python-Software mit vorzeigbarer Dokumentation. Die Software bekommt wahrscheinlich eh niemand zu Gesicht und ist zu schlecht programmiert (, d. h. ungelenk geschrieben, aber erfüllt ihren Zweck).

Wenn dir die Qualität von dem was du tust sowieso egal ist, kannst du natürlich machen was du willst.

[BlackJack]

@pixewakb: Es gibt ein PEP für Docstrings. Ansonsten kommt da halt das reST-Markup rein das auch Sphinx versteht. Mit dem Autodoc-Plugin bei Sphinx kann man dann diese Docstrings aus den Modulen in die Dokumentation ziehen. Wozu es natürlich praktisch wäre wenn die Quelltexte des Programms und die Quelltexte der Dokumentation in *einem* Projektverzeichnis existieren würden das unter einer echten Versionsverwaltung steht. Also so wie man das üblicherweise machen würde. Du verletzt ja aber sowieso schon alle normalen, sinnvollen Standards, fragst dann nach einem für die Dokumentation, gibst aber eigentlich schon vor dass Du das im Wiki machen willst. Also suchst Du eher jemanden der Dir bestätigt das das Wiki toll dafür ist und willst gar keine anderen antworten‽

Generierte Dokumentation in ein Wiki zu kippen halte ich für keine gute Idee, denn Wiki impliziert ja irgendwie das man das dann *dort* bearbeiten kann. Dann wird das aber beim nächsten generieren wieder überschrieben.

Wenn man die Dokumentation der Funktionen im Quelltext als Docstrings vornimmt und der Quelltext im Wiki gespeichert wird, dann wäre es doch irgendwie doppelt wenn man dann die generierte Doku auch noch mal ins Wiki stellt‽

[pixewakb]

Das ist alles kein Scherz. Am Wiki komme ich nicht vorbei, weil das quasi vorgegeben ist. Ein Großteil der Leute, die Python einsetzen, das ist meine Erfahrung, haben mit Programmierung von Hause aus wenig zu tun. An meinen Skripten arbeite ich allein, da hat sich für mich bislang weder eine Versionsverwaltung noch ein Bugtracker als nützlich erwiesen. Die Einarbeitungszeit ist ein weiteres Problem.

Mein Arbeitsprozess sieht so aus, dass ich momentan Funktionalität in Modulen bereitstelle und dann etliche Skripte schreibe, die auf Daten Operationen vollführen. Daran stricke ich dann solange, bis es läuft. Wenn eine Funktion gerade fehlt, mache ich wieder Grundlagenarbeit. Wie kann mir da eine Versionsverwaltung helfen, das ist aus meiner Sicht ein weiteres Programm, dass ich nicht im Blick behalten kann.

Ich habe mal angefangen Logfiles zu schreiben, war nett, aber letztendlich bin ich im Datenmüll ersoffen. Ich schreibe Berichte zu Datenauswertungen, aktuell packe ich die aufgetretenen Fehler einfach dort rein, kann die Fehler dann direkt fixen und anschließend das Skript neu ausführen, so dass es dann fehlerfrei läuft. Bei mir sieht es so aus: Entweder läuft das Skript oder es läuft nicht; wenn es nicht läuft, dann muss ich das zeitnah ändern. Wenn ich ein Skript starte, dann stehen oben etliche eigene Bibliotheken und wenige Standardbibliotheken; für mich ist es aber immer noch beherrschbar und momentan läuft es.

BTW: Wenn Du mich nach Literatur fragen würdest, momentan könnte ich bis Dezember durchlesen und hätte den Schreibtisch nicht leer. Die meisten Titel davon sind so kleine 200-Seiten-Schmöker für zwischendurch, einige andere schlagen dann mit 400-Seiten auf. Jede Einarbeitungszeit, die ich spare, ist großartig.

[pixewakb]

@BlackJack

@pixewakb: Es gibt ein PEP für Docstrings. Ansonsten kommt da halt das reST-Markup rein das auch Sphinx versteht. Mit dem Autodoc-Plugin bei Sphinx kann man dann diese Docstrings aus den Modulen in die Dokumentation ziehen.

PEP für Docstrings

Markup für Sphinx?

Wozu es natürlich praktisch wäre wenn die Quelltexte des Programms und die Quelltexte der Dokumentation in *einem* Projektverzeichnis existieren würden das unter einer echten Versionsverwaltung steht. Also so wie man das üblicherweise machen würde.

Die Einarbeitungszeit für eine Versionsverwaltung habe ich nicht. Das Konzept hat sich mir bislang auch noch nicht erschlossen.

Du verletzt ja aber sowieso schon alle normalen, sinnvollen Standards, fragst dann nach einem für die Dokumentation, gibst aber eigentlich schon vor dass Du das im Wiki machen willst. Also suchst Du eher jemanden der Dir bestätigt das das Wiki toll dafür ist und willst gar keine anderen antworten‽

Nein! Ich hatte nur erwartet, dass es "leichter" zu händeln wäre. Bei Sphinx sehe ich schon jetzt festgelegte Befehle usw., die mich abschrecken. Ich brauche es möglichst simpel (und würde mir notfalls wahrscheinlich kurz einen eigenen Parser schreiben, der die DocStrings ausliest und fürs Wiki aufbereitet. Nur sehe ich immer noch nicht, wie die Docstrings idealiter auszusehen haben...)

Was genau meinst du mit "alle normalen, sinnvollen Standards", also mehr als nur die Tatsache, dass ich keine Versionsverwaltung nutze, keinen Bugtracker und um Sphinx herum möchte oder noch was anderes!?

Mal zu meinem Problem: Eigentlich suche ich so etwas wie eine Präsentation o. ä. der Art "Quellcode dokumentieren in 10 Minuten" mit slides, wie eine gängige Beschreibung nach Python-Art und Standards-konform für die Parameter und Rückgabewerte aussehen kann. Für Java hatte ich das mal vor einigen Monaten in den Händen (und würde ich wahrscheinlich noch mal suchen). Da war dann je Klasse auf einem DIN A4-Blatt die Eigenschaften mit Datentyp und die Methoden mit Parametern und Rückgabewerten vermerkt. Das war schnell, einfach und eingängig.

Folgendes Problem zur Dokumentation: Ich brauche eigentlich so etwas wie einen Spickzettel für mich, so dass ich auch noch nach Monaten weiß, wie ich mit dem Tool arbeiten kann. Momentan habe ich fertige Skripte, wo ich mal einen Abschnitt ändere und neu speichere. Wenn ich da aber mal grundlegend neu heranwill, stehe ich auf dem Schlauch und muss mich wieder durch den Quelltext wühlen. Das Problem möchte ich mit möglichst wenig Aufwand lösen und mit dem Wiki kam ich bislang wirklich gut zurecht.

Bei meiner bisherigen Dokumentation arbeite ich mit Schaubildern, Grafiken, Tabellen usw. usf. da ist ein Wiki unschlagbar. Da, wo ich Quellcode dokumentiere, sind 90 % der Informationen Hintergrundinfos zum Grund, warum ich das mache und Überlegungen, wie ich da bestimmte Probleme lösen kann. Der beigefügte Quellcode ist dann fast schon nebensächlich.

Momentan habe ich zwischen 10 und 20 selbst geschriebene Module. 10 bis 20 Sphinx-Dokumentation in 10 bis 20 Ordnern ist nicht mehr zu machen. Da verliere ich den Überblick.

[cofi]

Mit dem Markup war das hier gemeint: http://sphinx-doc.org/domains.html#python-signatures

Das ist im Grunde das Javadoc Aequivalent. Ein entsprechendes Sphinx Dokument, das die dann einbettet ist mit autodoc dann auch nicht mehr als

Code: Alles auswählen

..automodule:: test

Ich glaube du suchst aber wohl wirklich nicht mehr als einen Docstring fuer ein Modul.

[sparrow]

Bei meiner bisherigen Dokumentation arbeite ich mit Schaubildern, Grafiken, Tabellen usw. usf. da ist ein Wiki unschlagbar.

Das klingt eher nach Powerpoint und ich nicht nach einem Wiki
Der Vorteil eines Wikis ist ja, dass jeder daran arbeitet.

Ich sehe das aber auch so, dass dir Docstrings reichen sollten. Ich habe auch Module in denen dern Quellcode doch eher wenig Platz im Verhältnis zu der Dokumentation in den Quelldateien verbraucht. Ein guter Editor kann die direkt ausblenden und ich habe beides übersichtlich beisammen.

Die anderen Werkzeuge, die man als Programmierer benutzen sollte (Versionsverwaltung, etc.) sollte man sich durchaus einmal anschauen. Eine Versionsverwaltung ist auch sinnvoll wenn man alleine daran arbeitet - und sehr oft fällt einem dabei auch auf wie man das in ganz anderen Bereichen verwenden kann. Wenn man damit zum Beispiel keine Projekte verwaltet, bei denen man programmiert sondern andere Sachen versioniert. Installationen von Binärprogrammen, Sachen die man sonst so am PC schreibt (Bücher, Briefe, ...) und ganz vieles mehr.

[jens]

Versionsverwaltung ist bei mit Pflicht.
Auch, wenn man nicht mit mehreren an einem Projekt arbeite, hat es mehrere Vorteile:

* dezentrales Backup ohne Probleme
* Man kann ältere Änderungen ansehen/wiederherstellen
* einfaches veröffentlichen (Auf github und Co. Packen und gut)

[snafu]

Gerade der von jens genannte Punkt der Wiederherstellungsmöglichkeit kann sehr hilfreich sein. Ich selbst war schon in mehreren Fällen froh, als ich mich irgendwie verzettelt hatte, dass ich mein Modul (oder gar mehrere voneinander abhängige Module) auf einen alten Stand zurückbringen konnte, in dem ein bestimmter Fehler nicht mehr aufgetreten ist. Manchmal merkt man auch nach einigem Herumgewurschtel, dass man am Ende den selben Effekt erzielt hat, nur mit weitaus komplizierterem Code. Auch dann ist ein Rollback, wie ihn Versionsverwaltungen bieten, sehr praktisch.

Ohne solche Tools müsste man unter Umständen alles wegwerfen und nochmal von grundauf neu schreiben oder mit beschissenem Code leben müssen, weil man sich nicht traut, den zu ändern oder - wenn's ganz übel kommt - das Projekt entnervt aufgeben. Das sind alles Dinge, die man vermeiden kann, wenn man sich angewöhnt, lauffähige Zwischenstände in die Versionsverwaltung zu überspielen.

EDIT: Wobei ein komplettes Neuschreiben natürlich auch *mit* Versionsverwaltung vorkommen kann. Das ist ja nicht grundsätzlich etwas schlechtes. Gerade wenn man sich mit einem Projekt auf völlig neues Terrain begibt, dann gehören Fehlkonzeptionen am Anfang schon fast dazu. Wichtig ist es nur, diese Fehler auch möglichst früh zu erkennen und dann notfalls wirklich nochmal neu anzufangen. Aber das nur am Rande...

[cofi]

Wenn ihr schon das zuruecksetzen auf alte Versionen erwaehnt und herausstellt, dass man damit an fehlerfreie Versionen kommt, betone ich mal, dass man damit auch ein wunderbares Tool hat um die Fehlerursache tatsaechlich auch zu finden. Mit `git bisect` gibt es zB ein Tool das direkt eine binaere Suche bereitstellt und mit einer entsprechenden Testsuite kann mans dann auch noch automatisieren.

[snafu]

Mit `git bisect` gibt es zB ein Tool das direkt eine binaere Suche bereitstellt und mit einer entsprechenden Testsuite kann mans dann auch noch automatisieren.

Übrigens: Hier wird weiter unten "bisect" anschaulich beschrieben.

[BlackJack]

Das mit dem Zurücksetzen muss sich auch nicht nur auf Fehler beziehen. Man hat ja auch manchmal Programme die auf bestimmten Daten arbeiten, mehr oder weniger nur einmal oder nicht allzuoft, und in einem Jahr bekommt man dann ähnliche Daten oder die Anforderungen verändern sich geringfügig und man ändert das Programm entsprechend, könnte dann aber die alten Daten zumindest nicht mit dem Ergebnis von damals nochmal verarbeiten. Da ist es dann schön wenn man solche Versionen getaggt in der Versionsverwaltung hat, für den Fall das man die alten Daten nochmal verarbeiten muss und das alte Programm dafür benötigt. Das könnte man dann sogar weiterentwickeln in einem eigenen Branch. So etwas manuell und nur mit einzelnen Dateien zu machen und da den Überblick zu behalten ist die Hölle!

Branches oder Klone eignen sich auch gut bei den von snafu erwähnten Konzeptionen. Man kann mal ausprobieren ob es besser ist dieses oder jenes anders zu lösen, auch wenn das länger dauert, und hat von jeder Variante die Versionshistorie, kann wegwerfen was nicht klappt, und hat jederzeit den stabilen, nicht-experimentellen Branch oder Klon.

[pixewakb]

Ganz vielen Dank!!!

Ich finde "Example Google Style Python Docstrings" eingängig.

http://sphinxcontrib-napoleon.readthedo ... oogle.html

Und werde das wahrscheinlich nutzen. Aktuell behelfe ich mir mit Versionen, die ich im Wiki speichere und einer Datensicherung über externe Laufwerke bzw. Server (automatisch). Eine öffentliche Versionsverwaltung scheidet von vornherein aus. Ich schaue es mir noch mal an; Versionsverwaltung klingt prinzipiell interessant, aber momentan brauche ich erst einmal (Zwischen)Ergebnisse.

Meine Erfahrung beim Bugtracker war, dass das einen Overhead produziert hat, den ich nicht mehr bewältigen konnte. Jetzt mache ich das via Notizen im Wiki und es funktioniert für mich. Überblick ist da für mich entscheidend.

PS Ich lerne noch. Vor absehbarer Zeit konnte ich nichts mit Klassen anfangen; mittlerweile arbeite ich fast nur noch damit. Vor einigen Jahren habe ich etwas mit PyQt gearbeitet, mittlerweile mache ich da nichts mehr mit. Ich schließe nicht aus, dass ich noch mal mit Bugtracker, Versionsverwaltung und Logdateien (die ich immer noch zusätzlich schreibe) intensiver arbeite. Nur momentan kann ich dem keine Priorität beimessen.

[jens]

Eine Versionsverwaltung zu nutzten, heißt nicht gleichzeitig, das dies öffentlich gemacht werden muss.

[pixewakb]

Ich kenne nur git(hub) und sourceforge und zwar mehr dem Namen nach und weniger, weil ich diese Plattformen aktiv nutze. Irgendeine Idee: crossplatform wäre gut, muss ich aber unter Windows nutzen können. Einfach zu lernen und einfach zu bedienen wäre auch gut, d. h. auch: intuitives GUI. Ich war nach diesem Thread über SVN gestolpert, aber das Angebot an Lösungen hat mich dann direkt wieder abgeschreckt.

[sparrow]

Github und Bitbucket sind nur Communities im Internet, die mit Daten aus Versionskontrollsystemen gefüttert werden. Versionieren tust du natürlich lokal und hast dort die Möglichkeit zu veröffentlichen. Gerade für OpenSource-Projekte ist das natürlich sehr hilfreich.

Git und Mercurial (hg) nehmen sich gegenseitig nicht viel, wobei Git halt "da draußen" sehr gehypt wird. Ich bevorzuge Mercurial, weil damals als ich ein Projekt anfing, git noch nicht so toll unter Windows funktionierte. Das soll sich aber geändert haben.

Die Lernkurve ist bei beiden recht steil, aber es lohnt sich auf jeden Fall.

Hier das deutsche Tutorial zu Mercurial. Unter Windows hakt sich das in den Windows-Explorer (das dürfte dann in etwa das sein, was du als "GUI" möchtest), aber eigentlich wird so etwas auf einer Kommandozeile verwendet.