Documente automáticamente todos los módulos de forma recursiva con Sphinx autodoc

Estoy tratando de usar Sphinx para documentar un proyecto de más de 5000 líneas en Python. Tiene alrededor de 7 módulos base. Hasta donde yo sé, para usar autodoc necesito escribir un código como este para cada archivo en mi proyecto:

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

Esto es demasiado tedioso porque tengo muchos archivos. Sería mucho más fácil si pudiera especificar que quiero que se documente el paquete ‘mods’. Sphinx podría luego revisar recursivamente el paquete y crear una página para cada submódulo.

¿Hay una característica como esta? Si no, podría escribir un script para hacer todos los archivos .rst, pero eso llevaría mucho tiempo.

Puedes comprobar esto guion que he hecho. Creo que te puede ayudar.

Esta secuencia de comandos analiza un árbol de directorios en busca de módulos y paquetes de python y crea archivos ReST de manera adecuada para crear documentación de código con Sphinx. También crea un índice de módulos.

ACTUALIZAR

Este script ahora es parte de Sphinx 1.1 como apidoc.

Desde Sphinx versión 3.1 (junio de 2020), sphinx.ext.autosummary (¡por fin!) tiene recursividad automática.

Por lo tanto, no es necesario codificar los nombres de los módulos ni depender de bibliotecas de terceros como Sphinx AutoAPI o Sphinx AutoPackageResumen para su detección automática de paquetes nunca más.

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 todos los módulos del paquete, por muy anidados que estén. Para cada módulo, luego resume cada atributo, función, clase y excepción en ese módulo.

Curiosamente, sin embargo, el valor predeterminado sphinx.ext.autosummary las plantillas no continúan generando 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.rst a mytoolbox/doc/source/_templates/custom-module-template.rst
• Copiar site-packages/sphinx/ext/autosummary/templates/autosummary/class.rst a mytoolbox/doc/source/_templates/custom-class-template.rst

el gancho en custom-module-template.rst es en index.rst arriba, usando el :template: opción. (Elimine esa línea para ver qué sucede con las plantillas de paquetes de sitio predeterminadas).

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 %}

No sé si Sphinx había tenido autosummary extensión en el momento en que se hizo la pregunta original, pero por ahora es muy posible configurar la generación automática de ese tipo sin usar sphinx-apidoc o guión similar. A continuación hay configuraciones que funcionan para uno de mis proyectos.

1. Permitir autosummary extensión (así como autodoc) en conf.py archivo y establezca su autosummary_generate opción a True. Esto puede ser suficiente si no está usando personalizado *.rst plantillas. De lo contrario, agregue su directorio de plantillas a la lista de exclusión, o autosummary intentará tratarlos como archivos de entrada (lo que parece ser un error).

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

2. Usar autosummary:: en el árbol TOC en su index.rst archivo. En este ejemplo de documentación para módulos project.module1 y project.module2 se generará automáticamente y se colocará en _autosummary directorio.

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

3. Por defecto autosummary generará solo resúmenes muy cortos para los módulos y sus funciones. Para cambiar eso, puede poner un archivo de plantilla personalizado en _templates/autosummary/module.rst (que se analizará con Jinja2):

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

En conclusión, no hay necesidad de mantener _autosummary directorio bajo control de versiones. Además, puede ponerle el nombre que desee y colocarlo en cualquier lugar del árbol de fuentes (colocándolo debajo _build aunque no funcionará).

Sphinx AutoAPI hace exactamente esto.

En cada paquete, el __init__.py archivo puede tener .. automodule:: package.module componentes para cada parte del paquete.

Entonces tú puedes .. automodule:: package y sobre todo hace lo que quieres.

Tal vez lo que estás buscando es Epydoc y esto Extensión de esfinge.