epydoc: Wie entfernt man bestimmte Einträge

[Manuelh87]

Hallo!

Ich habe heute endlich epydoc mit meinem python3 projekt zum laufen gebracht (War jetzt nicht weiters aufregend, hab nur das --parse-only flag für mich entdeckt). Hab leider nichts über epydoc und python3 gefunden.
Das ist vermutlich kein besonders guter Weg, aber zur Not hab ich noch pydoc3, das liest sich dann halt ein wenig kryptisch, aber besser als nichts...

Das eigentliche Problem, dass mich beschäftigt, ist aber, dass ich die docu gerne kürzen würde. Vorallem dass überall die methoden die 'object' zur Verfügung stellt, aufgelistet werden und auch private member (z.b.: _some_method()), ist irgendwie ungut... und das leider trotz --no-private.

Aufgerufen wird das ganze mit

Code: Alles auswählen

epydoc -v  --parse-only --pdf --no-private src/*.py

Verwendet wird die version 3.0.1 von epydoc (Ubuntu Repositories).

Das wirklich wichtige für mich wäre das Verstecken der geerbten Methoden von 'object'. Da das echt unnötig und lässtig ist. Docstrings hab ich grad vielleicht um die 10 Seiten und darauß wird gut mehr als das dreifache durch immer wiederkehrende Dinge wie Methoden von 'object'.

Hat vielleicht jemand schon ähnliche Probleme gehabt?

MFG Manuel

[Xynon1]

Nein, da die paar Methoden meist nicht stören , es gibt AFAIK keine vorkonfigurierte Einstellung in epydoc welche das ermöglichen könnte. Lediglich den "Style" kann man per "--inheritance [listed/grouped/included]" ändern. Auch für Python3 wird warscheinlich kein epydoc mehr gegeben, da soweit ich dem Projekt sich schon länger nichts mehr bewegt hat. Wenn du also mehr einstellen möchtest, dann musst du wohl sphinx nutzen. (oder dich in die Interna von epydoc einlesen und entsprechende Stellen selbst ändern)

[Manuelh87]

Hi! Danke für die rasche Antwort.
Ich habs befürchtet... Ja, sphinx hab ich schon öfter gelesen, habs grad installiert und ausprobiert, aber hab noch nicht herausgefunden, wie ich auf ähnlich schnelle weise wie bei epydoc die Doku erstellen kann. (Es scheint mir so als müsste man hier zwingend ein paar Dokumente erstellen und dort die entsprechenden Einträge machen damit er die Module dokumentiert..., was mir prinzipiell auch gefällt, da ich festlegen kann, was dokumentiert wird und auch noch massig Text dazuwurschteln kann)

Ein weiterers Problem ist, dass ich leider epytext oder wie das heißt verwendet hab, was leider echt blöd war, denn hätt ich reStructuredText verwendet, dann könnt ich beides nutzen... Nur irgendwie bekomm ich das nicht hin, dass reST dann ordentlich aussieht mit epydoc...

Code: Alles auswählen

"""Kurze Info

Ausführlicher bla Text...
Ausführlicher bla Text2

:Parameters:
  param1
    erklärung
  param2
    erklärung die etwas
    länger ist
"""

Mein docstring sieht so aus, aber im pdf steht Parameters immer in der selben Zeile wie 'Ausführlicher bla Text2'. Mach ich da was falsch, oder ist das eher ein Fehler von epydoc??
Langfristig gesehen ist es sicher besser auf sphinx zu wechseln, die Dokus sehen ja auch echt gut aus. Hat vielleicht wäre ne Ahnung was ich mit reST und epydoc falsch mach, dass das nicht ordentlich aussieht? Das wäre nämlich die Ideale Lösung... Da kann ich schön langsam Modul für Modul auf reST umstellen, und hätte trotzdem immer eine Dokumentation verfügbar... Bis ichs mich genug mit sphinx auseinandergesetzt hab und das verwenden kann...

MFG Manuel

[Xynon1]

Du musst, wenn ich mich recht erinnere, einfach oben im Modul mit angeben dass du reStructuredText nutzen möchtest. Dann sollte das epydoc auch als solchen interpretieren. Das müsste also so aussehen:

Code: Alles auswählen

__docformat__ = "restructuredtext en"

[Manuelh87]

Ja, ja, das hab ich gemacht... Es hat auch sonst alles funktioniert.... nur sieht das Ergebniss eben nicht so aus wie vorher als ich epytext verwendet hab, sondern Parameters steht noch im letzten Absatz... epydoc hätt sich sonst eh beschwert (hat es auch über eine Einrückung, dass hab ich aber danach behoben...).

Trotzdem siehst eben merkwürdig aus...
Er erkennt auch die parameter, also die werden hervorgehoben... nur fängt er keine neue Zeile für :Parameters: an...

Mach ich da was falsch??

[Xynon1]

Du solltest epydoc mal mit -v starten und prüfen ob ein Syntaxfehler vorhanden ist. Wenn nur ein Fehler drin ist, werden die Schlüsselwörter ignoriert.

[Manuelh87]

Hi!

Ich hatte zwar wirklich einen Fehler oben, aber wie gesagt, es wird ja alles schön erkannt.
Aber damit ich ganz sicher sein kann, hab ichs nochmal mit einem einfachen Text probiert.
Und durch Zufall sah es zuerst gut aus, aber es wird kein Zeilenumbruch gemacht (Ansonsten ist alles okay...). Ich will nicht kleinlich sein, aber das sieht einfach nicht schön aus...
Habs mit dem Code probiert:

Code: Alles auswählen

__docformat__ = "restructuredtext en"

def someBla(a, b, c):
    """Does just bla!
    
    The bla isn't really important. Just ignore the method
    it doesn't do anything. It's just useless... just useless.
    Really extremly useless.
    
    :Parameters:
        a
            Useless parameter a. Ignore it
            is useless.
        b
            As useless as a. But it's b
            not a.
        c
            This is really important. No, just kidding
            this is as useless as all the other parameters.
    """
    print(a,b,c)

Und es sieht wieder nicht gut aus. Also es stimmt alles, bis auf das 'Parameters' nicht in einer neuen Zeile steht... Keine Fehler beim erstellen (mit -v)
Kennt jemand eine Lösung für das Problem??

[Xynon1]

Wenn du meinst dass das nicht wie bei epytext aussieht, liegt es nur daran das du wohl etwas anderes geschrieben hast. Meinst du eventuell sowas?

Code: Alles auswählen

"""
:param a: Useless parameter a. Ignore it is useless.
:param b: As useless as a. But it's b not a.
:param c: This is really important. No, just kidding
          this is as useless as all the other parameters.
"""

Der einzige wirkliche Unterschied zwischen epytext und reStructeredText sollte der Doppelpunkt(:) statt dem @ sein und das epytext etwas weniger an Tags anbietet.

[BlackJack]

@Manuelh87: Das scheint ein Problem von `epydoc` bei der PDF-Ausgabe zu sein. Bei der HTML-Ausgabe wird es ordentlich formatiert. Aber mal ehrlich: Wer druckt denn solche Java-style API-Dokumentation aus? Das sind doch Unmengen an Seiten die hauptsächlich aus „boilerplate”-Text bestehen.

( Damit Aussenstehende wissen wovon wir reden, ist hier mal ein generiertes PDF zu dem Quelltext: http://ubuntuone.com/p/17cF/ )

@Xynon1: Das was Manuelh87 da geschrieben hat ist schon richtig. Man kann die einzelnen ``:param …:``-Felder so zusammenfassen und bekommt zumindest beim HTML die gleiche Ausgabe heraus.

[Xynon1]

Ok wusste ich leider nicht, dass es dort tatsächlich einen so erheblichen Fehler vorliegt.

Allerdings war mir auch immer schleierhaft warum man für eine solche(generierte) Dokumentation ein PDF- bzw. Text-Dokument erzeugen möchte und habe das bisher auch nicht getan. Ich empfinde soetwas unübersichtlich und kontraproduktiv. Es vermittelt nicht die Übersicht welche man sich wünschen würde, trotz der erzeugten Verknüpfungen. Hier bevorzuge ich immer noch eine richtige Dokumentation.

[Manuelh87]

Hi! Danke für eure Hilfe! Ja, es scheint wirklich ein Fehler zu sein und wenn ich mal Zeit und Lust hab, will ich mal nachsehen ob sich das ändern lässt, bzw. ob vielleicht das repository nicht aktuell ist und das ganze eh schon behoben wurde, keine Ahnung, aber das ist dann nicht so ein Problem...

Ausdrucken will ich das ganze eh nicht, das wäre wirklich unnötig. Allerdings würd ich ja gerade gerne den ganzen Mist los werden und nur die wichtigen Dinge drinnen haben...
Ich wollts nur leicht auf mein Handy geben damit ichs z.b.: im Zug überlegen kann, was z.b. bessere Namen für Funktionen wären, Dokumentation nachbessern, etc... was man halt so tun kann...

Das letzte mal hab ich die html version von pydoc verwendet und dachte mir irgendwie, ein pdf wäre nett... das ist aber vermutlich eh Blödsinn... Das ist jetzt auch kein wirkliches Problem, ich dachte es würde gernell nicht ordentlich funktionieren. Aber wenn das nur ein Fehler ist, der grad mal den pdf output betrifft, spielt das wirklich nicht so eine Rolle. Dann steht meinem baldigen Umstieg (oder auch nicht sooo bald) auf sphinx nichts im weg, wenngleich ich epydoc wirklich mag, aber es kommt halt nicht an eine richtige Doku rann...

Ich hab sphinx noch nicht ganz durchschaut, ist das eh sinnvoll, also kennt das dann eh die gleichen tags. Ich bin mir nämlich nicht sicher ob z.b.: :param xxx: und :keyword yyy: zu reStructuredText gehören, oder ob reStructuredText nur die Art und Weise wie tags deklariert werden bestimmt, aber die tags hier eben nur von epydoc verwendet werden, und sphinx nichts damit anfangen kann... Es ist mir grad nicht so wichtig dass ich das schnell hinbekomm, da es grad eh nicht so wichtig ist, aber ich möchte das bisschen was ich dokumentiere gleich richtig machen, sodass es, sobald ich mich mal damit gespielt hab, gleich eine tolle Grundlage für eine nützliche doku habe...