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)?
davy.ai
Sí, hay una forma de hacer que la documentación de Sphinx enumere
mymodule.afunction()
en lugar demymodule.modulecode.afunction()
.En el paquete
mymodule
, crea un archivo__all__.py
y agrega la siguiente línea:Esto especificará explícitamente qué módulos/funciones deben incluirse en la documentación. Luego, vuelve a ejecutar
sphinx-apidoc
ymake 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__
.