Automatische Dokumentation Generierung für alle Python Paket-Inhalt

Question

Ich bin zu versuchen, automatisch zu generieren grundlegende Dokumentation für meine Code-Basis Sphinx verwenden. Aber ich habe Schwierigkeiten, Sphinx anweist, rekursiv meine Dateien zu scannen.

Ich habe eine Python Code-Basis mit einer Ordnerstruktur wie:

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

Ich lief Sphinx-quickstart in <workspace>, so jetzt meine Struktur aussieht:

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

Ich habe das Quickstart Tutorial lesen http://sphinx.pocoo.org/tutorial.html , und zwar ich versuche immer noch die Dokumentation zu verstehen, wie es macht mich besorgt formuliert ist, dass Sphinx geht davon aus, ich werde manuell Dokumentationsdateien für jede einzelne Modul / Klasse / Funktion in meiner Code-Basis erstellen.

Allerdings habe ich Bekanntmachung der „automodule“ Aussage, und ich aktiviert Autodoc während quickstart, so bin ich der Hoffnung, den größten Teil der Dokumentation kann automatisch generiert werden. Ich änderte meine conf.py mein src Ordner sys.path hinzufügen und dann meine index.rst zu verwenden automodule modifiziert. So, jetzt meine index.rst aussieht:

Contents:

.. toctree::
   :maxdepth: 2

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

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

.. automodule:: alphabuyer
   :members:

Ich habe Dutzende von Klassen und in dem Subpackages definierten Funktionen. Doch wenn ich laufen:

sphinx-build -b html . ./_build

es berichtet:

updating environment: 1 added, 0 changed, 0 removed

Und dies scheint versagt zu haben irgendetwas in meinem Paket zu importieren. Anzeigen der erzeugten index.html zeigt nichts neben „Inhalt:“. Die Index-Seite zeigt nur „mypackage (Modul)“, sondern klicken sie zeigt, hat es auch keinen Inhalt.

Wie Sie Sphinx direkt rekursiv ein Paket zu analysieren und automatisch generieren Dokumentation für jede Klasse / Methode / Funktion es trifft, ohne manuell jede Klasse selbst Liste mit?

Answer 1

Vielleicht apigen.py can help: https://github.com/nipy/ nipy / Baum / Master / tools .

Dieses Werkzeug ist sehr kurz beschrieben hier: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912 .

Oder noch besser, verwenden PDOC .

---

Update: Sphinx-apidoc Dienstprogramm wurde hinzugefügt in Sphinx Version 1.1 .

Answer 2

Sie können versuchen, Sphinx-apidoc verwendet wird.

$ 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>.

Sie können Sphinx-apidoc mit Sphinx-Schnellstart, um das gesamte doc Projekt wie dieses mischen zu erstellen:

$ sphinx-apidoc -F -o docs project

Dieser Aufruf wird ein komplettes Projekt mit Sphinx-quickstart erzeugen und Look rekursiv in (Projekt) für Python-Module.

Hope, das hilft!

Answer 3

Hinweis

  

Für Sphinx (eigentlich die Python-Interpreter, der ausgeführt werden   Sphinx) Ihr Modul zu finden, muss es importierbar sein. Das bedeutet, dass   das Modul oder das Paket muss in einem der Verzeichnisse sein auf   sys.path - passen Sie Ihre sys.path in der Konfigurationsdatei entsprechend

Also, gehen Sie zu Ihrem conf.py und fügen

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

Jetzt ist Ihre index.rst sieht aus wie:

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

und

make html