ylab examples color categoryorder python documentation documentation-generation python-sphinx

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



plotly ylab (3)

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!

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?

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