web-dev-qa-db-fra.com

Génération automatique de la documentation pour tous Python Contenu du package

J'essaie de générer automatiquement la documentation de base pour ma base de code à l'aide de Sphinx. Cependant, j'ai du mal à demander à Sphinx d'analyser récursivement mes fichiers.

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

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

J'ai exécuté sphinx-quickstart dans <workspace>, maintenant ma structure ressemble à ceci:

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

J'ai lu le tutoriel de démarrage rapide http://sphinx.pocoo.org/tutorial.html , et bien que j'essaie toujours de comprendre les documents, la façon dont il est rédigé me fait craindre que Sphinx suppose Je vais créer manuellement des fichiers de documentation pour chaque module/classe/fonction unique dans ma base de code.

Cependant, j'ai remarqué l'instruction "automodule" et j'ai activé l'autodoc lors du démarrage rapide, j'espère donc que la plupart de la documentation pourra être générée automatiquement. J'ai modifié mon conf.py pour ajouter mon dossier src à sys.path, puis j'ai modifié mon index.rst pour utiliser automodule. Alors maintenant, mon index.rst 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-packages. Pourtant, quand je cours:

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. L'affichage du fichier index.html généré ne montre rien à côté de "Contenu:". La page d'index affiche uniquement "mypackage (module)", mais en cliquant dessus, il n'a également aucun contenu.

Comment demandez-vous à Sphinx d'analyser récursivement un package et de générer automatiquement de la documentation pour chaque classe/méthode/fonction qu'il rencontre, sans avoir à répertorier manuellement chaque classe vous-même?

pythondocumentationdocumentation-generationpython-sphinx
51
Cerin

Apigen.py peut peut-être 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 .

Ou mieux encore, utilisez pdoc .

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

17
mzjn

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 ceci:

$ sphinx-apidoc -F -o docs project

Cet appel va générer un projet complet avec sphinx-quickstart et Rechercher récursivement dans (projet) les modules Python.

J'espère que cela t'aides!

57
Daniel

Remarque

Pour que Sphinx (en fait, l'interpréteur Python qui exécute Sphinx) trouve votre module, il doit être importable. Cela signifie que le module ou le package doit se trouver dans l'un des répertoires sur sys.path - adaptez votre sys.path dans le fichier de configuration en conséquence

Alors, allez dans votre conf.py et ajoutez

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

Maintenant, votre index.rst ressemble à:

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

et

make html

5
macm