Generación automática de documentación para el Contenido del paquete Todo Python

Question

Estoy tratando de auto-generar documentación básica para mi base de código usando Sphinx. Sin embargo, estoy teniendo dificultades para instruir Sphinx para escanear de forma recursiva mis archivos.

Tengo 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é esfinge de inicio rápido en <workspace>, por lo que ahora la estructura de mi aspecto:

<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 me hace le preocupa que Sphinx supone que voy a crear manualmente archivos de documentación para cada módulo / clase / función individual en mi base de código redactado.

Sin embargo, me di cuenta de la "automodule" declaración, y Habilité autodoc durante el inicio rápido, así que espero que la mayor parte de la documentación se pueden generar de forma automática. He modificado mi conf.py añadir mi carpeta src para sys.path y luego modificado mi index.rst al uso automodule. Así que ahora mi aspecto index.rst como:

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. Visualización de la muestra index.html generado nada al lado de "Contenido". La página de índice sólo muestra "mypackage (módulo)", pero al hacer clic se nota que también no tiene contenido.

¿Cómo se dirige Sphinx para analizar un paquete de forma recursiva y generar automáticamente la documentación para todos los / método / función de clase se encuentra, sin tener a la lista manualmente cada clase ti mismo?

Answer 1

La ayuda puede Quizás apigen.py: https://github.com/nipy/ nipy / árbol / maestro / herramientas .

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

O mejor aún, utilizan PDOC .

---

Actualización: se añadió la href="http://sphinx.pocoo.org/invocation.html#invocation-of-sphinx-apidoc" rel="nofollow noreferrer"> utilidad esfinge apidoc versión 1.1 .

Answer 2

Puede intentar usar esfinge 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 como esto:

$ sphinx-apidoc -F -o docs project

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

Espero que esto ayude!

Answer 3

Nota:

  

Para Esfinge (en realidad, el intérprete de Python que se 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 archivo de configuración en consecuencia

Así que, vaya a su conf.py y añadir

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

Ahora su apariencia index.rst como:

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

y

make html