Usando Sphinx para construir documentación de paquetes de Python#
En esta página presentamos como utilizar Sphinx para construir la documentación orientada a los usuarios de tu paquete. Aunque Sphinx es la herramienta más común en la ecosistema de Python científico, puedes explorar otras herramientas para construir documentación como mkdocs que está ganando popularidad en el ecosistema de empaquetado de Python.
Truco
Ejemplos de sitios del web de documentación que nos gustan:
Sphinx - un generador de sitios estáticos#
Sphinx es un generador de sitios estáticos. Un generador de sitios estáticos es una herramienta que crea HTML para un sitio web basado en plantillas. Los archivos HTML se sirven «estáticamente», lo que significa que no hay generación ni modificación de los archivos en línea.
Sphinx está desarrollado en Python.
La documentación creada con Sphinx puede ser personalizada con extensiones y temas#
La funcionalidad de Sphinx puede ser extendida con extensiones y temas. Algunos ejemplos incluyen:
Puedes usar temas de documentación para generación rápida de documentaciónhermosa.
Puedes ejecutar y probar ejemplos del código en los docstrings usando la extensión doctest
Aunque Sphinx se basa en sintaxis
rSTde forma nativa, puedes añadir intérpretes de sintaxis personalizadas para usar otras sintaxis más fáciles con herramientas como MyST.
Temas comúnes en Sphinx#
Puedes usar cualquiera tema de Sphinx que prefieras. Sin embargo, los temas más comúnes utilizados en la comunidad de Python científico incluyen:
Truco
Este archivo se crea con Sphinx y el tema furo.