examples - Generación automática de documentación para todos los contenidos del paquete Python

plotly ylab

Question

Estoy tratando de generar automáticamente la documentación básica para mi base de código con Sphinx. Sin embargo, tengo dificultades para instruir a Sphinx para que escanee mis archivos de manera recursiva.

Tengo una base de código de Python con una estructura de carpetas como:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2

Ejecuté sphinx-quickstart en <workspace> , así que ahora mi estructura se ve así:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2
    index.rst
    _build
    _static
    _templates

He leído el tutorial de inicio rápido http://sphinx.pocoo.org/tutorial.html , y aunque todavía estoy tratando de entender los documentos, la forma en que está redactado me preocupa que Sphinx asuma que voy a crear manualmente archivos de documentación para cada módulo / clase / función en mi código base.

Sin embargo, sí noté la instrucción "automodule" y habilité el autodoc durante el inicio rápido, así que espero que la mayoría de la documentación se pueda generar automáticamente. Modifiqué mi conf.py para agregar mi carpeta src a sys.path y luego modifiqué mi index.rst para usar automodule. Así que ahora mi index.rst se ve así:

Contents:

.. toctree::
   :maxdepth: 2

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

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

.. automodule:: alphabuyer
   :members:

Tengo docenas de clases y funciones definidas en los subpaquetes. Sin embargo, cuando corro:

sphinx-build -b html . ./_build

informa:

updating environment: 1 added, 0 changed, 0 removed

Y parece que esto no ha podido importar nada dentro de mi paquete. Ver el index.html generado no muestra nada al lado de "Contenido:". La página de índice solo muestra "mypackage (módulo)", pero al hacer clic se muestra que tampoco tiene contenido.

¿Cómo se puede hacer para que Sphinx analice de forma recursiva un paquete y genere automáticamente documentación para cada clase / método / función que encuentre, sin tener que enumerar manualmente todas las clases usted mismo?

Answer 1

Puedes intentar usar sphinx-apidoc.

$ sphinx-apidoc --help
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_paths, ...]

Look recursively in <module_path> for Python modules and packages and create
one reST file with automodule directives per package in the <output_path>.

Puedes mezclar sphinx-apidoc con sphinx-quickstart para crear todo el proyecto de doc como este:

$ sphinx-apidoc -F -o docs project

Esta convocatoria generará un proyecto completo con sphinx-quickstart y Look recursively en (proyecto) para módulos de Python.

¡Espero que esto ayude!

Answer 2

Quizás apigen.py puede ayudar: https://github.com/nipy/nipy/tree/master/tools .

Esta herramienta se describe muy brevemente aquí: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912 .

Actualización: la utilidad sphinx-apidoc se agregó en la versión 1.1 de Sphinx.

Answer 3

Nota

Para Sphinx (en realidad, el intérprete de Python que ejecuta Sphinx) para encontrar su módulo, debe ser importable. Eso significa que el módulo o el paquete debe estar en uno de los directorios en sys.path - adapte su sys.path en el archivo de configuración en consecuencia

Por lo tanto, vaya a su conf.py y agregue

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

Ahora su index.rst se ve así:

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

y

make html