python - sphinxs - sphinx documentation generator

Sphinx autodoc no es lo suficientemente automático

Question

Intento usar Sphinx para documentar un proyecto de más de 5,000 líneas en Python. Tiene aproximadamente 7 módulos base. Por lo que 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 quería que se documentara el paquete ''mods''. Sphinx podría examinar el paquete de forma recursiva y crear una página para cada submódulo.

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

Answer 1

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

Entonces puede .. automodule:: package y generalmente hace lo que quiere.

Answer 2

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

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

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

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

   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 es necesario mantener el directorio _autosummary bajo control de versión. Además, puede ponerle el nombre que desee y _build en cualquier lugar del árbol de fuentes (sin embargo, ponerlo debajo de _build no funcionará).

Answer 3

Puedes verificar este script que hice. Creo que puede ayudarte.

Esta secuencia de comandos analiza un árbol de directorios en busca de módulos y paquetes 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 .

Answer 4

Tal vez lo que estás buscando es Epydoc y esta extensión de Sphinx .