Génération automatique de la documentation pour tous les contenus de paquet Python

Question

Je suis en train de générer automatiquement la documentation de base pour ma base de code à l'aide de Sphinx. Cependant, j'ai de la difficulté à les instruire de Sphinx à analyser récursivement mes fichiers.

J'ai une base de code Python avec une structure de dossier comme:

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

J'ai couru sphinx-démarrage rapide en <workspace>, alors maintenant, ma structure ressemble à:

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

J'ai lu le didacticiel de démarrage rapide http://sphinx.pocoo.org/tutorial.htmlet même si je suis encore à essayer de comprendre les docs, la façon dont il est rédigé me rend inquiète de ce que le Sphinx suppose que je vais créer manuellement des fichiers de documentation pour chaque module/classe/fonction dans mon code.

Cependant, j'ai remarqué la "automodule" déclaration, et j'ai activé l'autodoc cours de démarrage rapide, alors j'espère que la plupart des documents peuvent être générés automatiquement. J'ai modifié mon conf.py pour ajouter mon dossier src de sys.chemin d'accès, puis modifié mon index.premier à utiliser automodule. Alors maintenant, mon index.tvd ressemble:

Contents:

.. toctree::
   :maxdepth: 2

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

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

.. automodule:: alphabuyer
   :members:

J'ai des dizaines de classes et de fonctions définies dans les sous-paquets. Pourtant, quand je le lance:

sphinx-build -b html . ./_build

il rapporte:

updating environment: 1 added, 0 changed, 0 removed

Et cela semble avoir échoué à importer quoi que ce soit à l'intérieur de mon colis. La visualisation de l'généré index.html ne montre rien, à côté de "Contenu:". La page d'Index montre que "mypackage (module)", mais en cliquant dessus, elle n'a pas de contenu.

Comment avez-vous direct Sphinx à analyser de manière récursive un paquet et de générer automatiquement la documentation pour chaque classe/méthode/fonction il rencontre, sans avoir à manuellement la liste de chaque classe vous-même?

Answer 1

Vous pouvez essayer d'utiliser sphinx-apidoc.

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

Vous pouvez mélanger sphinx-apidoc avec sphinx-quickstart afin de créer l'ensemble du projet doc comme suit:

 $ sphinx-apidoc -F -o docs project
 

Cet appel générera un projet complet avec sphinx-quickstart et Look récursivement dans (projet) pour les modules Python.

J'espère que cela t'aides!

Answer 2

Peut-être apigen.py peut aider: https://github.com/nipy/nipy/tree/master/tools.

Cet outil est décrit très brièvement ici: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912.

---

Mise à jour: le sphinx-apidoc utilitaire a été ajouté dans Sphinx version 1.1.

Answer 3

Note

Pour le Sphinx (en fait, l'interpréteur Python qui s'exécute Sphinx) pour trouver votre module, il doit être importable. Cela signifie que le module ou le package doit être dans l'un des répertoires sur sys.chemin – d'adapter votre sys.chemin d'accès dans le fichier de configuration en conséquence

Donc, allez à votre conf.py et d'ajouter

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

Maintenant, votre index.tvd ressemble:

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

et

make html