Wie benutzt man Sphinx?

[Steffo]

Hallo,
ich glaub, ich bin zu blöd, um Sphinx zu benutzen.
Das, was als First Steps bezeichnet wird, fängt in meinen Augen mitten drin an.
Wo soll ich denn den Befehl "sphinx-quickstart" eingeben? Sowohl in der Windows-Shell als auch unter Python führt das zu Fehlermeldungen.
Welcher Schritt fehlt, damit das funktioniert?

Danke im Voraus!

L. G.
Steffo

[Sr4l]

First steps beginnt nach der Installation von Sphinx.

Wenn du es installiert hast findet sich unter "C:\Python27\Scripts" sphinx-quickstart und andere Befehle.

Du musst also diesen Ordner zu der Umgebungsvariable PATH hinzufügen oder sphinx mit absolute Pfadangabe aufrufen.

[Steffo]

Du musst also diesen Ordner zu der Umgebungsvariable PATH hinzufügen oder sphinx mit absolute Pfadangabe aufrufen.

Ah, an der Umgebungsvariable lags, danke!

[Steffo]

Hallo,
weiß jemand, wie man das autodoc-Modul benutzt?
Ich würde gerne automatisch, ohne expliziten Angaben, alle Module, Funktionen, Klassen und Methoden dokumentieren.
Irgendwie gibt die Doku dazu keine Auskunft. Sie gibt Beispiele für explizite Dokumentation von Klassen und Methoden, aber wer macht sich schon die Arbeit und zählt alles einzeln auf?!

Danke im Voraus!

L. G.
Steffo

[lunar]

@Steffo Jeder, der eine strukturierte Dokumentation möchte. Dann nämlich muss man alles sinnvoll gruppieren und sortieren, und das kann kein Tool automatisch.

[Steffo]

Muss ich wirklich jedes Modul, jede Klasse und jede Methode einzeln aufzählen?!

EDIT: autodoc scheint gewisse Module, die importiert werden, automatisch zu importieren. Wenn das Modul jedoch als Python-Plugin installiert wurde, erhalte ich eine Fehlermeldung von autodoc:

ImportError: No module named serial

C:\Documents and Settings\stdi3650\My Documents\Aptana Studio 3 Workspace\COM-CommunicatorV6\index.rst:19:
WARNING: autodoc can't import/find class 'view.GUI.GUI', it reported error: "No module named serial", please check your spelling and sys.path

Nun habe ich in conf.py folgendes eingefügt:

Code: Alles auswählen

sys.path.insert(0, os.path.abspath('src'))
sys.path.insert(1, 'C:\Python25\Lib\site-packages')

Leider hilft das auch nicht weiter.

[BlackJack]

@Steffo: Es gibt IIRC eine Möglichkeit ein Grundgerüst von reStructuredText-Dateien für Python-Module/Pakete automatisch erstellen zu lassen.

Was ist ein Python-Plugin? Falls Du meinst, dass Du PySerial zusätzlich installiert hast, dann müsste das gefunden werden. Dein Programm findet es ja auch, nehme ich mal an. Also was ist an der Laufzeitumgebung von Deinem Programm dann anders als bei Sphinx? Führst Du Sphinx mit dem selben Python aus, dass auch Dein Programm verwendet?

Wenn Du keine „freie Text”-Dokumentation willst, dann könntest Du mal einen Blick auf Epydoc werfen. Das generiert eher so etwas wie JavaDoc oder Doxygen.

[Steffo]

Also was ist an der Laufzeitumgebung von Deinem Programm dann anders als bei Sphinx? Führst Du Sphinx mit dem selben Python aus, dass auch Dein Programm verwendet?

Genau so ist es! Danke!

Wenn Du keine „freie Text”-Dokumentation willst, dann könntest Du mal einen Blick auf Epydoc werfen.

Das ist wohl besser für mich geeignet, danke!

L. G.
Steffo

[Steffo]

Irgendwie funktioniert nichts richtig!
epydoc startet plötzlich mein Programm, wenn ich mein Hauptmodul angebe!

Code: Alles auswählen

epydoc.py --html src -o docs

Was ist das für ein Mist?!

[BlackJack]

@Steffo: Mit statischer Analyse kommt man bei dynamischen Programmiersprachen halt nicht so weit, also muss man bei solchen Werkzeugen auch immer damit rechnen, dass sie die zu untersuchenden Module importieren. An der Stelle könnte man jetzt fragen: Warum startet Dein Programm wenn man das Modul importiert. Unit-Tests könnte man für das Modul so ja auch nicht schreiben. Deinem Modul fehlt das hier:

Code: Alles auswählen

if __name__ == '__main__':
    main()

Und in der `main()`-Funktion steht dann der Code der das Programm startet.

[Steffo]

Freut mich, dass es hier im Forum so kompetente Leute gibt.
Danke!!!

L. G.
Steffo