Pitón autodocumento usando sphinx

Question

Esta es una versión generalizada de un Pregunta anterior sobre Sphinx.

¿Hay alguna forma de módulos o paquetes de autodocumento recursivamente que contengan clases y funciones dentro de ellos?

Creo que es una tontería agregar el autofunction o automodule directiva para cada función; Debe haber una manera de automatizar el proceso, de lo contrario no veo el punto de usar Sphinx en absoluto.

Aclaración:En vez 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 requiere que yo corte y pegado manualmente todos los nombres de métodos y actualice la documentación correspondientemente, quiero tener un comando como:

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. MAGIC COMMAND: Automatically print the docstrings and signatures 
           of all Seg() methods.

Answer 1

Usamos

.. automodule:: module
   :members:

Answer 2

Para facilitar las cosas, puede usar este script (mire la parte inferior de la página para obtener la última versión):http://bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenererate-script-to-sphinx

Este script analizará sus paquetes/módulos y generará todos los archivos de reposo necesarios para construir el DOC a partir de documentos.

Soy el autor original de este guión.

ACTUALIZAR

Este script ahora es parte de Sphinx 1.1 como apidoc.

Answer 3

El guión de Etienne, mencionado en su respuesta, ahora se ha integrado en Sphinx como Sphinx-Apidoc. Hace exactamente lo que el OP quiere. Está programado para su lanzamiento en Sphinx 1.1, o está disponible en el repositorio de HG:

https://bitbucket.org/birkenfeld/sphinx

Funciona maravillosamente 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>.

Answer 4

Creo que es una tontería agregar la directiva de autofunción o automode para cada función; Debe haber una manera de automatizar el proceso, de lo contrario no veo el punto de usar Sphinx en absoluto.

Yo sugeriría Epydoc, que se especializa en generar documentación a partir de documentos.

Answer 5

¿Lo desea más simple que solo especificar Automodule? Incluso para una biblioteca grande, es una cantidad de trabajo de 5 minutos para escribir todos los nombres de módulos.

La razón de hacerlo es porque Sphinx apenas adivina lo que debe documentarse.

También puede escribir AutoPackage, que buscaría módulos y usaría la Directiva Automodule (si Automodule aún no lo hace).