[sphinx] autodoc Einstieg

[MoonKid]

Ich versuche gerade mit Sphinx meinen Code dokumentiert zu bekommen.
Aber scheinbar verstehe ich an dem sphinx-Konzept selbst etwas falsch.

In meinem Ergebnis (html) sehe ich zwar die Klassen bzw. Module, jedoch diese ohne Inhalt. Keine Methoden, keine Member, nix. Hab hier auch mal eine Testklasse "foo" mit eingebaut, aus der offiziellen sphinx-docu.

Code: Alles auswählen

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

Und so sieht mein build-Script aus, das direkt im source-root ausgeführt wird.

Code: Alles auswählen

#!/bin/bash
rm -r ./doc
sphinx-apidoc -F -o doc/src .
sphinx-build -b html doc/src doc
/usr/bin/x-www-browser doc/index.html &

autodoc ist auch per default schon aktiviert

Code: Alles auswählen

user@MONSTER:~/share/work/Project$ cat doc/src/conf.py | grep ext.autodoc
    'sphinx.ext.autodoc',

Nach meinem Verständnis, müsste sphinx doch aus dem obigen Code alle doc-strings rausziehen und die Member entsprechend im html-file darstellen, oder?

[cofi]

Nein, so funktioniert autodoc nicht. Du brauchst RST Quellen die an geeigneten stellen die autodoc Direktiven aufrufen, siehe http://sphinx-doc.org/ext/autodoc.html

[BlackJack]

@cofi: Ich hatte das so verstanden das der ``sphinx-apidoc``-Aufruf die RST-Dateien, bzw. ein komplettes Sphinxprojekt aus dem Python-Quelltext erstellt.

[MoonKid]

@cofi: Ich hatte das so verstanden das der ``sphinx-apidoc``-Aufruf die RST-Dateien, bzw. ein komplettes Sphinxprojekt aus dem Python-Quelltext erstellt.

Exakt, so verstehe ich das auch.

Die Doku und die Struktur liegt bereits vor - im Python code. sphinx muss das nur ordentlich parsen. Und genau dafür ist es (nach meinem Verständnis) auch da. Wenn ich da jetzt noch irgendwelche extra files für die Doku anlegen müsste, kann ich es mir auch sparen.

[BlackJack]

@MoonKid: Sphinx ist kein JavaDoc-Klon. Wenn Du so etwas suchst, dann schau Dich besser nach etwas anderem um.

[MoonKid]

Die Doku zu apidoc ist eigentlich ziemlich klar. Da wird alles automatisch erzeugt.

Auch von der Logik her besteht keinerlei Notwendigkeit noch irgendwelche extra Dateien anzulegen, da sphinx bereits alle notwendigen Infos zur Verfügung hat.

Aber es geht hier nicht ums Konzept.
Was müsste ich den tun, um z.B. den obigen Beispiel-Code dokumentiert zu bekommen?

[cofi]

Den Aufruf von `sphinx-apidoc` habe ich uebersehen. Das erzeugt tatsaechlich alle noetigen Skelette.

Kann es sein, dass du beim enstprechenden `make html` Aufruf Fehlermeldungen siehst, dass dein `foo` Modul nicht importiert werden kann? Dann bleibt der Link bleibt weiterhin wichtig:

Note

For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly.

Aber um es nochmal zu betonen: Die Staerke von sphinx ist, dass der Source nicht die Struktur der Doku vorgibt.

[MoonKid]

Tatsache da sind import Fehler.

Hab jetzt diese zwei Zeilen in mein build-script abgeändert.

Code: Alles auswählen

#!/bin/bash
rm -r ./doc
sphinx-apidoc -F -o doc/src .
echo "sys.path.insert(0, '/home/user/share/work')" >> doc/src/conf.py
echo "sys.path.insert(0, '/home/user/share/work/MuckiBude')" >> doc/src/conf.py
sphinx-build -b html doc/src doc
/usr/bin/x-www-browser doc/index.html &

Es gibt aber weitere import Probleme. Ich nutze z.B. "ObjectListView" als Klasse (mit pip installiert). Das Modul dazu sucht er auch. Soll er aber nicht. Er soll einfach nur das generieren, was er findet und den Rest Rest sein lassen.
Wenn ich ObjectListView im "exclude_pattern" mit eintrage, ändert das nix.

ObjectListView ist eine externe Komponente und soll auch gar nicht dokumentiert werden.

[BlackJack]

@MoonKid: Deine Module werden importiert und wenn diese weitere Module importieren werden die natürlich auch importiert. Nochmal: Sphinx ist kein JavaDoc-Klon. Das als solchen verwenden zu wollen ist ein schwimmen gegen den Strom.

[cofi]

Ich lass dann mal den Epydoc link hier liegen: http://epydoc.sourceforge.net/

Oh ich merke gerade, dass das wohl tot ist .. gibt es da eine lebendige Alternative?

[BlackJack]

pydoctor vom Twisted-Projekt wäre wohl ein Ersatz.

[MoonKid]

Habs hinbekommen. Lag an zwei Dingen:

1. Ein Bug in der Python2 version von apidoc
2. Vermischung von Python2 (Sphinx) mit Python3 (mein Code)

Das Script hier funktioniert prima im Wurzelverzeichnis des Python-Projektes vorrausgesetzt Sphinx ist Python3 (sudo pip3 install -U Sphinx) und der eigenen Code auch.

Code: Alles auswählen

#!/bin/bash
rm -r ./doc
sphinx-apidoc -F -o doc/src ${PWD}
echo "sys.path.insert(0, '${PWD}')" >> doc/src/conf.py
echo "sys.path.insert(0, '${PWD}/..')" >> doc/src/conf.py
sphinx-build -b html doc/src doc
/usr/bin/x-www-browser doc/index.html &