web-dev-qa-db-fra.com

L'autodoc Sphinx n'est pas assez automatique

J'essaie d'utiliser Sphinx pour documenter un projet de plus de 5 000 lignes en Python. Il a environ 7 modules de base. Pour autant que je sache, pour utiliser l'autodoc, j'ai besoin d'écrire du code comme celui-ci pour chaque fichier de mon projet:

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

C'est beaucoup trop fastidieux car j'ai beaucoup de fichiers. Ce serait beaucoup plus facile si je pouvais simplement spécifier que je voulais que le paquet "mods" soit documenté. Sphinx pourrait alors parcourir récursivement le package et créer une page pour chaque sous-module.

Existe-t-il une fonctionnalité comme celle-ci? Sinon, je pourrais écrire un script pour créer tous les fichiers .rst, mais cela prendrait beaucoup de temps.

pythonpython-sphinx
137
Cory Walker

Vous pouvez vérifier cela script que j'ai fait. Je pense que cela peut vous aider.

Ce script analyse une arborescence de répertoires à la recherche de modules et packages python et crée les fichiers ReST de manière appropriée pour créer la documentation du code avec Sphinx. Il crée également un index des modules.

[~ # ~] mise à jour [~ # ~]

Ce script fait maintenant partie de Sphinx 1.1 comme apidoc.

130
Etienne

Je ne sais pas si Sphinx avait eu l'extension autosummary au moment où la question d'origine a été posée, mais pour l'instant il est tout à fait possible de configurer une génération automatique de ce type sans utiliser sphinx-apidoc Ou un script similaire. Vous trouverez ci-dessous des paramètres qui fonctionnent pour l'un de mes projets.

  1. Activez l'extension autosummary (ainsi que autodoc) dans le fichier conf.py Et définissez son option autosummary_generate Sur True. Cela peut suffire si vous n'utilisez pas de modèles *.rst Personnalisés. Sinon, ajoutez votre répertoire de modèles pour exclure la liste, ou autosummary essaiera de les traiter comme des fichiers d'entrée (ce qui semble être un bogue).

    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
autosummary_generate = True
templates_path = [ '_templates' ]
exclude_patterns = ['_build', '_templates']

  2. Utilisez autosummary:: Dans l'arborescence de la table des matières de votre fichier index.rst. Dans cet exemple, la documentation des modules project.module1 Et project.module2 Sera générée automatiquement et placée dans le répertoire _autosummary.

    PROJECT
=======

.. toctree::

.. autosummary::
   :toctree: _autosummary

   project.module1
   project.module2

  3. Par défaut, autosummary ne générera que des résumés très courts pour les modules et leurs fonctions. Pour changer cela, vous pouvez mettre un fichier de modèle personnalisé dans _templates/autosummary/module.rst (Qui sera analysé avec Jinja2 ):

    {{ fullname }}
{{ underline }}

.. automodule:: {{ fullname }}
    :members:

En conclusion, il n'est pas nécessaire de garder le répertoire _autosummary Sous contrôle de version. En outre, vous pouvez le nommer comme vous le souhaitez et le placer n'importe où dans l'arborescence source (le mettre en dessous de _build Ne fonctionnera cependant pas).

32
firegurafiku

Dans chaque package, le __init__.py le fichier peut avoir .. automodule:: package.module composants pour chaque partie du package.

Ensuite vous pouvez .. automodule:: package et il fait surtout ce que vous voulez.

11
S.Lott

Peut-être que ce que vous cherchez est Epydoc et ceci extension Sphinx .

1
Edward Dale