L'autodoc Sphinx n'est pas assez automatique

J'essaie d'utiliser Sphinx pour documenter un projet de plus de 5000 lignes en Python. Il a environ 7 modules de base. Pour autant que je sache, pour utiliser autodoc, je dois écrire un 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 de nombreux 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.

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

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

METTRE À JOUR

Ce script fait maintenant partie de Sphinx 1.1 car qu'apidoc .

Je ne sais pas si Sphinx avait eu une autosummaryextension au moment où la question initiale 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-apidocou script similaire. Ci-dessous, il y a des paramètres qui fonctionnent pour l'un de mes projets.

1. Activez l' autosummaryextension (ainsi que autodoc) dans le conf.pyfichier et définissez son autosummary_generateoption sur True. Cela peut suffire si vous n'utilisez pas de *.rstmodèles personnalisés . Sinon, ajoutez votre répertoire de modèles à la liste d'exclusion, ou autosummaryessayez 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 dans votre index.rstfichier. Dans cet exemple de documentation pour les modules project.module1et project.module2sera généré automatiquement et placé dans le _autosummaryrépertoire.

   PROJECT
   =======
   
   .. toctree::
   
   .. autosummary::
      :toctree: _autosummary
   
      project.module1
      project.module2

3. Par défaut, autosummaryne générera que des résumés très courts pour les modules et leurs fonctions. Pour changer cela, vous pouvez insérer 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 _autosummaryrépertoire sous contrôle de version. De plus, vous pouvez le nommer comme vous le souhaitez et le placer n'importe où dans l'arborescence des sources (le placer ci-dessous _buildne fonctionnera cependant pas).

Dans chaque package, le __init__.pyfichier peut avoir des .. automodule:: package.modulecomposants pour chaque partie du package.

Ensuite, vous pouvez .. automodule:: packageet il fait principalement ce que vous voulez.

À partir de la version 3.1 de Sphinx (juin 2020), sphinx.ext.autosummary(enfin!) A la récursivité.

Donc pas besoin de coder en dur les noms de modules ou de s'appuyer sur des bibliothèques tierces comme Sphinx AutoAPI ou Sphinx AutoPackage pour leur détection automatique des paquets.

Exemple de package Python 3.7 à documenter ( voir le code sur Github et le résultat sur ReadTheDocs ):

mytoolbox
|-- mypackage
|   |-- __init__.py
|   |-- foo.py
|   |-- mysubpackage
|       |-- __init__.py
|       |-- bar.py
|-- doc
|   |-- source
|       |--index.rst
|       |--conf.py
|       |-- _templates
|           |-- custom-module-template.rst
|           |-- custom-class-template.rst

conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # Source code dir relative to this file

extensions = [
    'sphinx.ext.autodoc',  # Core library for html generation from docstrings
    'sphinx.ext.autosummary',  # Create neat summary tables
]
autosummary_generate = True  # Turn on sphinx.ext.autosummary

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

index.rst(notez la nouvelle :recursive:option):

Welcome to My Toolbox
=====================

Some words.

.. autosummary::
   :toctree: _autosummary
   :template: custom-module-template.rst
   :recursive:

   mypackage

Cela suffit pour résumer automatiquement chaque module du package, même profondément imbriqué. Pour chaque module, il récapitule ensuite chaque attribut, fonction, classe et exception de ce module.

Curieusement, cependant, les sphinx.ext.autosummarymodèles par défaut ne génèrent pas de pages de documentation séparées pour chaque attribut, fonction, classe et exception, et établissent des liens vers eux à partir des tableaux récapitulatifs. Il est possible d'étendre les modèles pour ce faire, comme indiqué ci-dessous, mais je ne comprends pas pourquoi ce n'est pas le comportement par défaut - c'est sûrement ce que la plupart des gens voudraient ..? Je l'ai soulevé comme une demande de fonctionnalité .

J'ai dû copier les modèles par défaut localement, puis y ajouter:

• Copier site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstversmytoolbox/doc/source/_templates/custom-module-template.rst
• Copier site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstversmytoolbox/doc/source/_templates/custom-class-template.rst

Le crochet dans custom-module-template.rstest en index.rstdessus, en utilisant l' :template:option. (Supprimez cette ligne pour voir ce qui se passe en utilisant les modèles de packages de site par défaut.)

custom-module-template.rst (lignes supplémentaires notées à droite):

{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}
  
   {% block attributes %}
   {% if attributes %}
   .. rubric:: Module Attributes

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in attributes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block functions %}
   {% if functions %}
   .. rubric:: {{ _('Functions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block classes %}
   {% if classes %}
   .. rubric:: {{ _('Classes') }}

   .. autosummary::
      :toctree:                                          <-- add this line
      :template: custom-class-template.rst               <-- add this line
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: {{ _('Exceptions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Modules

.. autosummary::
   :toctree:
   :template: custom-module-template.rst                 <-- add this line
   :recursive:
{% for item in modules %}
   {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

custom-class-template.rst (lignes supplémentaires notées à droite):

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:                                    <-- add at least this line
   :show-inheritance:                           <-- plus I want to show inheritance...
   :inherited-members:                          <-- ...and inherited members too

   {% block methods %}
   .. automethod:: __init__

   {% if methods %}
   .. rubric:: {{ _('Methods') }}

   .. autosummary::
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: {{ _('Attributes') }}

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

C'est exactement ce que fait Sphinx AutoAPI .

Peut-être que vous recherchez Epydoc et cette extension Sphinx .