Utilizando autosummary

Nota

Acá se explica cómo configurar y usar autosummary, antes se debe configurar como se indica en la receta.

La documentación va a consistir con una página principal que tiene una descripción simple y varios links, cada uno lleva a la documentación de un módulo que está en una página separada.

Hay que hacer dos archivos .rst: uno es el index y otro es una plantilla que se utiliza para generar la documentación de cada módulo.

Esto se hace gracias a la extensión autosummary. Esta extensión crea un archivo .rst para cada módulo a partir de la plantilla. Estos archivos .rst generados a partir de la platilla se guardan en docs/source/_autosummary/.

Luego a partir de el index.rst y de cada .rst generado, se crea la documentación en HTML.

Nota

autosummary por defecto no reemplaza los archivos .rst ya generados, por lo tanto si se cambia la plantilla hay que borrar la carpeta docs/source/_autosummary/ para que se genere nuevamente y se vean reflejados los cambios.

Nota

Para entender mejor cuál es el trabajo que hace autosummary mirar en qué consiste el método manual.

Configurar

Esto se hace en conf.py.

• Agregar la extension sphinx.ext.autosummary en la lista extensions.
• En cualquier lado poner autosummary_generate = True.

Escribir

Editar index.rst y dejarlo algo así:

Documentación de mi proyecto
============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Esta es una introducción a lo que hace este proyecto...

.. autosummary::
   :toctree: _autosummary

   miproyecto.mimodulo1
   miproyecto.mimodulo2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Nota

Yo escribí miproyecto.modulo1. Esto debe ser el módulo a documentar tal cual uno lo importa desde Python. Depende de qué se haya agregado al path en conf.py.

Después crear una plantilla, el archivo sería docs/source/_templates/autosummary/module.rst. Dentro debe llevar escrito lo que estará en la página de cada módulo. Hice una plantilla que para mí es mejor que la que viene por defecto:

{{ fullname }}
{{ underline }}

.. currentmodule:: {{ fullname }}

{% block functions %}
{% if functions %}
.. rubric:: Functions

.. autosummary::
{% for item in functions %}
  {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block classes %}
{% if classes %}
.. rubric:: Classes

.. autosummary::
{% for item in classes %}
  {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block exceptions %}
{% if exceptions %}
.. rubric:: Exceptions

.. autosummary::
{% for item in exceptions %}
  {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

.. automodule:: {{ fullname }}
   :members:
   :private-members:

Continuar

Ahora solamente falta generar la documentación!.