À 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.autosummary
modè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.rst
versmytoolbox/doc/source/_templates/custom-module-template.rst
- Copier
site-packages/sphinx/ext/autosummary/templates/autosummary/class.rst
versmytoolbox/doc/source/_templates/custom-class-template.rst
Le crochet dans custom-module-template.rst
est en index.rst
dessus, 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 %}
ls
vers un fichier et de le modifier?