Doxygen -> Doxypy Dokumentation

[Dennis X. (Gast)]

Hallo zusammen,
bei einem größeren Python Projekt würde ich gerne ein wenig mit Doxygen 
arbeiten. Erfahrung in anderen Sprachen und der Dokumentation ist 
bereits vorhanden, aber bei Python ist das alles etwas anders.
Jetzt hab ich gesehen, dass es DoxyPy und DoxyPyPy (!) gibt um die 
Dateien vorzuverarbeiten. Es gibt scheinbar auch noch so ein paar 
andere. Aber so ganz rund sieht mir das alles noch nicht aus.
Mir würde reichen, wenn alle Variablen einen Kommentar hätten und die 
Funktionen mit Parametern + Return Werte und vielleicht ein zwei Zeilen 
Text.

Hat da jemand einen Rat? Hat das schonmal jemand sauber benutzt oder 
etwas ähniches?

Grüße
Dennis

[Kaj (Gast)]

Python bringt pydoc mit:
https://docs.python.org/3.5/library/pydoc.html#module-pydoc


foo.py

def foo(arg1, arg2):
    """Diese Funktion macht folgendes:

    <hier beschreibung einfügen>

    Argumente:
        arg1: <beschreibung>
        arg2: <beschreibung>

    Return:
        Gibt <was auch immer> zurück
    """

    #hier Code

Und dann in der Konsole:

pydoc -w foo

Dann bekommst du eine foo.html

Hilft dir das?

Grüße

[Kaj (Gast)]

Darüber hinaus ist Sphinx weit verbeitet um Pythondokumentationen zu 
erstellen, aber damit komme ich irgendwie nicht klar :-/
http://www.sphinx-doc.org/en/stable/

Mit Epydoc hab ich noch nicht gearbeitet:
http://epydoc.sourceforge.net/
http://epydoc.sourceforge.net/manual-docstring.html

[Olaf (Gast)]

> Hat da jemand einen Rat?

Jetzt mal ganz ehrlich. Hast du schon jemals so einen Doxygen 
generierten Scheiss gelesen? Nein? Alles ich wuerde es sein lassen. Das 
Zeug ist nur gut um mit einem tausend seitigen Ausdruck davon einen 
Powerpointanbeter todzuwerfen.

Olaf

[Hannes J. (Firma: _⌨_) (pnuebergang)]

Olaf schrieb:
> Jetzt mal ganz ehrlich. Hast du schon jemals so einen Doxygen
> generierten Scheiss gelesen? Nein? Alles ich wuerde es sein lassen. Das
> Zeug ist nur gut um mit einem tausend seitigen Ausdruck davon einen
> Powerpointanbeter todzuwerfen.

Doxygen ist auch nur ein Werkzeug. Wer (in den Quelltext) Müll 
reinschreibt bekommt auch nur Müll raus. Wer sich Mühe gibt bekommt 
etwas vernünftiges raus.

Programmierer tendieren leider dazu, weil sei keine Lust, kein Talent 
oder kein Verständnis für Dokumentation haben, Müll reinzuschreiben. Um 
das beschissene Ergebnis dann auf das Tool zu schieben.

[Dennis X. (Gast)]

Kaj schrieb:
> Dann bekommst du eine foo.html
>
> Hilft dir das?
>
> Grüße

Hallo Kaj, ja danke das ist auch schon sehr gut. Geht das auch irgendwie 
mit Variablen? Hab so einige (konstante) Werte die ich gerne 
dokumentieren möchte. Sowie ich das jetzt sehen konnte, macht pydoc auch 
gleich -die meisten- Links voll automatisch oder? Gibt es da noch ein 
Menü groß drum herum? Wie sieht das aus mit der Dokumentation eines 
ganzen Projektes? Schreib ich mir dann ein Skript, welches alle Dateien 
konvertiert?

Kaj schrieb:
> Darüber hinaus ist Sphinx weit verbeitet um Pythondokumentationen zu
> erstellen

Schau mir das auch mal an, ich werde berichten.

@Hannes: Ja so ist es leider, ich mach mir meist die Mühe, zumindest 
wenn andere Leute damit auch noch arbeiten sollen.

[Kaj (Gast)]

So, ich hab gerade einbisschen mit Epydoc rumgespielt und ich muss 
sagen:
Der Output gefaellt mir viel besser als von pydoc.

Epydoc:
http://epydoc.sourceforge.net/
http://epydoc.sourceforge.net/manual-epytext.html
http://epydoc.sourceforge.net/manual-usage.html

main.py

#!/usr/bin/env python

#:  docstring for global x
x = 24
y = 25 #: docstring for global y


class Test:
    s_x = 26
    """docstring for class variable Test.s_x"""

    def __init__(self):
        self.var = 27
        """docstring for instance variable Test.var"""



def main(a, b):
    """
    Return the value of a + b + global values x and y

    @type   a: number
    @param  a: first value
    @type   b: number
    @param  b: second value

    @rtype:    number
    @return:   a + b + static values
    """

    return a + b + x + y


if __name__ == '__main__':
    y = main(3, 7)
    print("y is = {0}".format(y))

und dann einfach Epydoc aufrufen mit:

epydoc --html main.py

Wenn du nichts weiteres angibst wird jetzt ein ordner "html"  erstellt, 
in dem die Doku liegt.
Der PDF Output gefaellt mir auch sehr gut. (statt --html einfach mit 
--pdf aufrufen)

Das Dokumentieren von Variablen (hier x und y) funktioniert offenbar nur 
fuer globale variablen, aber nicht fuer Variablen in einer Funktion.

Ich spiel damit mal noch einbisschen rum.

[Dennis X. (Gast)]

Das sieht in der Tat echt nett aus! Vor allem gefällt mir, dass er 
scheinbar die docstrings oberhalb und daneben in die Doku mit rein 
nimmt.
Damit wären die Variablen auch dokumentiert. Genau das geht aktuell mit 
Doxygen nicht.

Danke für deine Versuche!

EDIT : Ah okay das mit den globalen Variablen und lokalen Variablen 
hab ich grad erst gelesen. Falls du da noch was findest lass es uns 
bitte wissen!