Dokumentation automatisch für alle Python-Paketinhalte generieren

Ich versuche zum automatischen erzeugen von basic-Dokumentation für meine Codebasis mit Sphinx. Allerdings werde ich Schwierigkeiten haben, anweist Sphinx rekursiv Scannen meine Dateien.

Habe ich ein Python-Codebasis mit einer Ordner-Struktur wie:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2

Ich lief sphinx-quickstart in <workspace>so nun meine Struktur sieht wie folgt aus:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2
    index.rst
    _build
    _static
    _templates

Gelesen habe ich das quickstart-tutorial http://sphinx.pocoo.org/tutorial.htmlund obwohl ich bin immer noch versuchen zu verstehen, die docs, die Art, wie es formuliert ist, macht mich besorgt, dass Sphinx übernimmt werde ich manuell erstellen Dokumentationen-Dateien für jedes einzelne Modul/Klasse/Funktion in meinem codebase.

Habe ich jedoch bemerken, dass das "automodule" - Anweisung, und ich konnte autodoc während quickstart, ich hoffe also, dass der Großteil der Dokumentation kann automatisch generiert werden. Ich veränderte meine conf.py um meinen src-Ordner sys.Pfad und dann meine modifizierten index.Erster automodule. So nun meine index.erste sieht wie folgt aus:

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. automodule:: alphabuyer
   :members:

Ich habe Dutzende Klassen und Funktionen definiert, die in der Unterpakete. Doch, wenn ich ausführen:

sphinx-build -b html . ./_build

berichtet Sie:

updating environment: 1 added, 0 changed, 0 removed

Und das scheint fehlgeschlagen zu importieren, alles, was in meinem Paket. Anzeigen der generierten index.html zeigt nichts weiter zu "Inhalt:". Die Index-Seite zeigt nur "MeinPaket (Modul)", aber anklicken zeigt es hat auch keinen Inhalt.

Wie haben Sie direkten Sphinx rekursiv analysieren eines Pakets und werden automatisch generiert Dokumentation für jede Klasse/Methode/Funktion auf die es trifft, ohne dass Sie manuell Liste jeder Klasse selbst?

InformationsquelleAutor der Frage Cerin | 2011-01-06

17

Vielleicht apigen.py helfen können: https://github.com/nipy/nipy/tree/master/tools.

Diesem tool beschrieben ist, ganz kurz hier: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912.

Update: die sphinx-apidoc unterbreitet utility Hinzugefügt wurde, in Sphinx version 1.1.

InformationsquelleAutor der Antwort mzjn
50

Können Sie versuchen, mit sphinx-apidoc unterbreitet.
```
$ sphinx-apidoc --help
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_paths, ...]

Look recursively in <module_path> for Python modules and packages and create
one reST file with automodule directives per package in the <output_path>.
```
Können Sie mischen sphinx-apidoc unterbreitet mit sphinx-quickstart um die ganze doc-Projekt wie folgt:
```
$ sphinx-apidoc -F -o docs project
```
Dieser Aufruf erzeugt ein komplettes Projekt mit dem sphinx-quickstart und Schauen Sie rekursiv in (Projekt -) für Python-Module.

Hoffe, das hilft!

InformationsquelleAutor der Antwort Daniel
4

Hinweis

Für Sphinx (eigentlich den Python-interpreter, ausgeführt wird
Sphinx) zu finden, dein Modul, es muss importiert werden kann. Das bedeutet, dass
das Modul oder das Paket muss in einem der Verzeichnisse auf
sys.Pfad – Anpassung der sys.Pfad in der Konfigurationsdatei entsprechend

So, gehen Sie zu Ihrem conf.py und fügen Sie
```
import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2
```
Nun Ihre index.erste sieht wie folgt aus:
```
.. toctree::
   :glob:

   example
   an_example_pypi_project/*
```
und

make html

InformationsquelleAutor der Antwort macm

Schreibe einen Kommentar

Du musst angemeldet sein, um einen Kommentar abzugeben.