read - Autodocumentar Python utilizando Sphinx
sphinx search (5)
Creo que es una tontería agregar la directiva de autofunción o automódulo para cada función; Debe haber una forma de automatizar el proceso, de lo contrario no veo el punto de usar Sphinx.
Sugeriría Epydoc , que está especializado en generar documentación a partir de cadenas de documentación.
Esta es una versión generalizada de una pregunta anterior relacionada con Sphinx .
¿Hay alguna forma de autodocumentar recursivamente módulos o paquetes que contengan clases y funciones dentro de ellos?
Creo que es una tontería agregar la directiva de autofunction o automodule para cada función; Debe haber una forma de automatizar el proceso, de lo contrario no veo el punto de usar Sphinx.
Aclaración: En lugar de:
.. automodule:: segments.segments
.. autoclass:: segments.segments.Seg
.. automethod:: Seg.method_1
.. automethod:: Seg.method_2
.. automethod:: Seg.method_3
.......
.. automethod:: Seg.method_n
Lo que me obliga a cortar y pegar manualmente todos los nombres de métodos y actualizar la documentación correspondiente, quiero tener un comando como:
.. automodule:: segments.segments
.. autoclass:: segments.segments.Seg
.. MAGIC COMMAND: Automatically print the docstrings and signatures
of all Seg() methods.
¿Quieres que sea más simple que especificar un automódulo? Incluso para una biblioteca grande, es una cantidad de trabajo de 5 minutos escribir todos los nombres de los módulos.
La razón para hacerlo es porque Sphinx apenas adivina lo que necesita ser documentado.
También puede escribir el empaquetado automático, que buscaría los módulos y usaría la directiva automodule (si automodule ya no lo hace).
El guión de Etienne, mencionado en su respuesta, ahora se ha integrado en Sphinx como esfinge-apidoc. Hace exactamente lo que quiere el OP. Está programado para su lanzamiento en Sphinx 1.1, o está disponible en el repositorio de Hg:
https://bitbucket.org/birkenfeld/sphinx
Funciona muy bien para mí. Los documentos leen así:
> sphinx-apidoc --help
Usage: sphinx-apidoc-script.py [options] -o <output_path> <module_path>
[exclude_paths, ...]
Look recursively in <module_path> for Python modules and packages and create
a reST file with automodule directives per package in the <output_path>.
Para facilitar las cosas, puede usar este script (mire en la parte inferior de la página la última versión): http://bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenerate-script-to-sphinx
Este script analizará sus paquetes / módulos y generará todos los demás archivos necesarios para compilar el documento a partir de cadenas de documentación.
Soy el autor original de este guión.
ACTUALIZAR
Este script ahora es parte de Sphinx 1.1 como apidoc .
Usamos
.. automodule:: module
:members: