Dokumentationserstellung mit sphinx

[niederrheiner]

Hallo an Alle,
seit ein paar Tagen versuche ich mit Hilfe von sphinx für ein Python-Projekt eine Dokumentation zu erstellen. Ich habe versucht mich im Internet kundig zu machen und bin dabei auf folgende Seite gestossen:
http://scriptsonscripts.blogspot.de/20 ... thon.html
Ich habe versucht das dort aufgeführte Beispiel nachzubauen. Es ist mir aber nicht ganz gelungen. Nach Ausführung des Befehls:

Code: Alles auswählen

sphinx-apidoc -F -o docs sphinxy

fehlt bei mir die Datei

Code: Alles auswählen

docs/package1.rst

Ich habe die gleiche Verzeichnisstruktur wie im Beispiel:

Code: Alles auswählen

code
└── py
    └── sphinxy
        ├── docs
        │   ├── big.rst
        │   ├── _build
        │   │   ├── doctrees
        │   │   │   ├── big.doctree
        │   │   │   ├── environment.pickle
        │   │   │   └── index.doctree
        │   │   └── html
        │   │       ├── big.html
        │   │       ├── genindex.html
        │   │       ├── index.html
        │   │       ├── objects.inv
        │   │       ├── search.html
        │   │       ├── searchindex.js
        │   │       ├── _sources
        │   │       │   ├── big.txt
        │   │       │   └── index.txt
        │   │       └── _static
        │   │           ├── ajax-loader.gif
        │   │           ├── alabaster.css
        │   │           ├── basic.css
        │   │           ├── comment-bright.png
        │   │           ├── comment-close.png
        │   │           ├── comment.png
        │   │           ├── doctools.js
        │   │           ├── down.png
        │   │           ├── down-pressed.png
        │   │           ├── file.png
        │   │           ├── jquery-1.11.1.js
        │   │           ├── jquery.js
        │   │           ├── minus.png
        │   │           ├── plus.png
        │   │           ├── pygments.css
        │   │           ├── searchtools.js
        │   │           ├── underscore-1.3.1.js
        │   │           ├── underscore.js
        │   │           ├── up.png
        │   │           ├── up-pressed.png
        │   │           └── websupport.js
        │   ├── conf.py
        │   ├── index.rst
        │   ├── make.bat
        │   ├── Makefile
        │   ├── _static
        │   └── _templates
        └── sphinxy
            ├── big.py
            ├── package1
            │   ├── __pycache__
            │   │   ├── small1.cpython-35.pyc
            │   │   └── small2.cpython-35.pyc
            │   ├── small1.py
            │   └── small2.py
            └── __pycache__
                └── big.cpython-35.pyc

Ich verwende Python 3.5 und python-sphinx 1.4.1-2 unter 4.5.1-1-ARCH

Meine Fragen:
Weshalb wird bei mir, im Gegensatz zum Beispiel, nicht package1.rst erstellt?
Liege ich richtig mit meiner Annahme, das ich mit der ,im Beispiel, beschriebenen Vorgehensweise ein Python-Projekt, welches mir Docstrings versehen ist, ohne manuellen Eingriff dokumentieren kann?

Danke für Eure Hilfe und Tipps.
Bis dann ...
MfG
Günter

[BlackJack]

@niederrheiner: Bei Deiner Verzeichnisstruktur fehlt eine entscheidende Datei die in dem verlinkten Blogbeitrag vorhanden ist. Dein Verzeichnis `package1` ist aus Python-Sicht kein Package sondern einfach nur ein Verzeichnis.

Man kann so wahrscheinlich ein Projekt ohne manuellen Eingriff dokumentieren, aber wünschenswert ist das IMHO nicht. Man reduziert Sphinx damit auf so etwas wie JavaDoc, was ich persönlich nicht wirklich gut finde weil das dazu verführt viel offensichtliches zu dokumentieren, auf der anderen Seite aber grössere Zusammenhänge oft nicht in der Dokumentation stehen weil die auf der Ebene der Funktionen, Klassen, und Methoden nicht so wirklich den richtigen Platz haben.

Das Beispiel für die Dokumentation einer Web-API in dem Blogbeitrag würde ich nicht mit reinem reST setzen, da gibt es in `sphinx-contrib` ein Plugin für. Das hat den Vorteil das die API auch im generierten Index landen kann, was bei reiner Textauszeichnung nicht der Fall ist.

[niederrheiner]

Hallo BlackJack,
danke für Deine Antwort.

@niederrheiner: Bei Deiner Verzeichnisstruktur fehlt eine entscheidende Datei die in dem verlinkten Blogbeitrag vorhanden ist. Dein Verzeichnis `package1` ist aus Python-Sicht kein Package sondern einfach nur ein Verzeichnis.

Man kann so wahrscheinlich ein Projekt ohne manuellen Eingriff dokumentieren, aber wünschenswert ist das IMHO nicht. Man reduziert Sphinx damit auf so etwas wie JavaDoc, was ich persönlich nicht wirklich gut finde weil das dazu verführt viel offensichtliches zu dokumentieren, auf der anderen Seite aber grössere Zusammenhänge oft nicht in der Dokumentation stehen weil die auf der Ebene der Funktionen, Klassen, und Methoden nicht so wirklich den richtigen Platz haben.

Das Beispiel für die Dokumentation einer Web-API in dem Blogbeitrag würde ich nicht mit reinem reST setzen, da gibt es in `sphinx-contrib` ein Plugin für. Das hat den Vorteil das die API auch im generierten Index landen kann, was bei reiner Textauszeichnung nicht der Fall ist.

Deine Anmerkungen zu Sinn oder Unsinn dieser Dokumentationsart kann ich im Moment nicht beurteilen, da mir die notwendige Kenntnis in der Dokumentation von Python-Programmen/-Projekten fehlt. Ich stehe erst am Anfang Lernkurve. Deshalb will ich erst mit einem kleinen, überschaubaren Beispiel beginnen und mich dann weiter vorarbeiten.

Die fehlende Datei `package1` ist mir ja auch aufgefallen, und deshalb habe ich ja diesen Beitrag ins Forum abgesetzt.
Ich bin davon ausgegangen, das `sphinx-apidoc` ab dem angegeben Verzeichnis innerhalb und unterhalb nach entsprechenden Dateien sucht und diese entsprechend verwertet.
In dem angeführten Beispiel ist es ja so. Warum bei mir nicht? Das ist die eigentliche Frage. Die anderen, von Dir, angesprochenen Punkte werden sicherlich zu einem späteren Zeitpunkt für mich relevant werden, wenn ich ein breiteres Basiswissen in Sachen Programmdokumentation habe. Dann werde ich vielleicht auch das Eine oder Andere besser verstehen.

Nochmals Danke für Deine Antwort.

Bis dann ...
MfG
Günter

[BlackJack]

@niederrheiner: Es geht nicht um eine fehlende Datei die Sphinx nicht generiert hat, sondern um eine Datei die *Du* vorher nicht angelegt hast, die im Beispiel aber vorhanden ist. Das Verzeichnis `package1` ist aus Python-Sicht kein Package sondern einfach nur ein Verzeichnis. Um daraus ein Package zu machen fehlt in dem Verzeichnis eine Datei: `__init__.py`.

[niederrheiner]

Hallo BlackJack,
danke für Deine Antwort. Ich hab's endlich begriffen. Kleine Ursache, grosse Wirkung. Nun klappt es auch wie gewünscht. Jetzt kann ich weiter experimentieren.

@niederrheiner: Es geht nicht um eine fehlende Datei die Sphinx nicht generiert hat, sondern um eine Datei die *Du* vorher nicht angelegt hast, die im Beispiel aber vorhanden ist. Das Verzeichnis `package1` ist aus Python-Sicht kein Package sondern einfach nur ein Verzeichnis. Um daraus ein Package zu machen fehlt in dem Verzeichnis eine Datei: `__init__.py`.

Nochmals Danke für Deine Hilfe.

Bis bis dann ...
MfG
Günter