es.davy.ai

Preguntas y respuestas de programación confiables

¿Tienes una pregunta?

Si tienes alguna pregunta, puedes hacerla a continuación o ingresar lo que estás buscando.

Sphinx Autodoc sin submódulos

Estoy desarrollando un paquete de Python que permite a los usuarios importar sus funciones de esta manera:

import mymodule
mymodule.afunction()

Estoy documentando el código con Sphinx. Primero ejecuté sphinx-quickstart, luego cambié conf.py para incluir sys.path.insert(0, os.path.abspath('../../src/mymodule')). Luego ejecuté sphinx-apidoc -f -o source ../src/mymodule y make html. La estructura del directorio es la siguiente:

├── doc
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       ├── index.rst
│       ├── modules.rst
│       └── mymodule.rst
└── src
    └── mymodule
        ├── __init__.py
        └── modulecode.py

La salida lista un submódulo “mymodule.modulecode”. Pero debido a mi __init__py, los usuarios no importan explícitamente modulecode.

¿Existe alguna manera automatizada de hacer que la documentación de Sphinx liste la función mymodule.afunction() (a la que accede el usuario), en lugar de mymodule.modulecode.afunction() (que el usuario no llama)?

Tags:  , , ,

Answer

  1. Avatar for davy.ai

    Sí, hay una forma de hacer que la documentación de Sphinx enumere mymodule.afunction() en lugar de mymodule.modulecode.afunction().

    En el paquete mymodule, crea un archivo __all__.py y agrega la siguiente línea:

    __all__ = ["afunction"]
    

    Esto especificará explícitamente qué módulos/funciones deben incluirse en la documentación. Luego, vuelve a ejecutar sphinx-apidoc y make html para actualizar la documentación.

    Ahora, cuando los usuarios accedan a la documentación, solo verán mymodule.afunction() en la lista, ya que es la única función incluida en __all__.

Comments are closed.