Generación automática de documentación para todo el contenido del paquete Python

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.

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

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

me encontré con una esfinge de inicio rápido en <workspace>, por lo que ahora mi estructura se parece a:

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

He leído la guía de inicio rápido tutorial 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, 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 parece:

Contents: 

.. toctree:: 
    :maxdepth: 2 

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

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

.. automodule:: alphabuyer 
    :members: 

Tengo docenas de clases y funciones definidas en las sub-paquetes. Sin embargo, cuando corro:

sphinx-build -b html . ./_build 

informa:

updating environment: 1 added, 0 changed, 0 removed 

Y esto parece haber dejado de importar cualquier cosa 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 dirige Sphinx para analizar de forma recursiva un paquete y generar automáticamente la documentación para cada clase/método/función que encuentra, sin tener que enumerar manualmente todas las clases usted mismo?

Answer 1

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 añadió en Sphinx version 1.1.

Answer 2

Puede probar el uso de 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>. 

Usted puede mezclar esfinge apidoc con una esfinge de inicio rápido con el fin de crear todo el proyecto doc así:

$ sphinx-apidoc -F -o docs project 

Esta llamada va a generar un proyecto completo con una esfinge de inicio rápido y Look de forma recursiva en (proyecto) para módulos de Python.

Espero que esto ayude!

Answer 3

Nota

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

lo tanto, ir a su conf.py y añadir

import an_example_pypi_project.useful_1 
import an_example_pypi_project.useful_2 

Ahora su index.rst parece:

.. toctree:: 
    :glob: 

    example 
    an_example_pypi_project/* 

y

make html