Desde la versión 3.1 de Sphinx (junio de 2020), sphinx.ext.autosummary(¡finalmente!) Tiene recursividad.
Por lo tanto, no es necesario codificar los nombres de los módulos ni confiar en bibliotecas de terceros como Sphinx AutoAPI o Sphinx AutoPackageSummary para su detección automática de paquetes.
Ejemplo de paquete de Python 3.7 para documentar ( ver código en Github y resultado en 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(nota nueva :recursive:opción):
Welcome to My Toolbox
=====================
Some words.
.. autosummary::
:toctree: _autosummary
:template: custom-module-template.rst
:recursive:
mypackage
Esto es suficiente para resumir automáticamente cada módulo del paquete, por muy anidado que esté. Para cada módulo, resume cada atributo, función, clase y excepción en ese módulo.
Sin embargo, curiosamente, las sphinx.ext.autosummaryplantillas predeterminadas no generan páginas de documentación separadas para cada atributo, función, clase y excepción, y se vinculan a ellas desde las tablas de resumen. Es posible extender las plantillas para hacer esto, como se muestra a continuación, pero no puedo entender por qué este no es el comportamiento predeterminado, seguramente eso es lo que la mayoría de la gente querría ... Lo he planteado como una solicitud de función .
Tuve que copiar las plantillas predeterminadas localmente y luego agregarlas:
- Copiar
site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstamytoolbox/doc/source/_templates/custom-module-template.rst
- Copiar
site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstamytoolbox/doc/source/_templates/custom-class-template.rst
El gancho en custom-module-template.rstestá index.rstarriba, usando la :template:opción. (Elimine esa línea para ver qué sucede usando las plantillas predeterminadas de paquetes de sitio).
custom-module-template.rst (líneas adicionales anotadas a la derecha):
{{ 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 (líneas adicionales anotadas a la derecha):
{{ 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 %}
lsa un archivo y editarlo?