Cómo configurar Sphinx para documentar su código Python

Sphinx es una de las herramientas más populares para generar documentación. En toda la comunidad de Python, los desarrolladores utilizan este software gratuito y de código abierto. Puede extraer texto directamente de su código o archivos de descuento y luego usarlo para generar documentación en varios formatos, como texto sin formato, HTML, PDF y EPUB.

Configuración de la esfinge

Antes de configurar Sphinx, eche un vistazo a lo que hace y algunas de sus características principales.

¿Qué es Sphinx y qué hace?

Como se mencionó, Sphinx es un generador de documentación. De forma predeterminada, utiliza el lenguaje de marcado reStructuredText (RST), pero a través de extensiones de terceros, también puede use Markdown, el popular lenguaje de marcado de texto sin formato. Luego convierte estos archivos RST o Markdown a HTML, PDF, páginas de manual u otros formatos que prefiera.

Algunas de las funciones que incluye Sphinx son:

• Capacidad para generar documentación a partir de código.
• Capacidad para hacer referencias cruzadas a diferentes páginas de documentos utilizando enlaces automáticos para funciones, clases, citas y términos del glosario.
• Resaltado de sintaxis para bloques de código.
• Compatibilidad con temas que pueden cambiar la apariencia de los documentos.
• Fácil definición del árbol del documento a través de una tabla de contenido.
• Capacidad de integración con extensiones de terceros para agregar más funciones a los documentos, como probar fragmentos de código.

Instalación de esfinge

Antes de instalar Sphinx, asegúrese de tener Python 3 instalado en su entorno de desarrollo. Luego puede usar el administrador de paquetes pip para instalar Sphinx ejecutando el siguiente comando en su terminal:

pip instalar esfinge

Esto descargará e instalará Sphinx y sus dependencias.

Después de la instalación, ejecute lo siguiente en el símbolo del sistema.

sphinx-build --version

Si todo funcionó bien, debería ver el número de versión del paquete Sphinx que acaba de instalar.

Creación de un nuevo proyecto de esfinge

Una vez que haya instalado Sphinx, navegue a su directorio de trabajo y ejecute el comando sphinx-quickstart para crear un nuevo proyecto de Sphinx.

sphinx-inicio rápido

Este comando le pedirá que responda una serie de preguntas sobre cómo configurar su proyecto Sphinx. Puede especificar el nombre del proyecto y utilizar las opciones predeterminadas para las demás preguntas. En el futuro, es posible que desee personalizar las respuestas en función de su proyecto.

Si enumera el contenido de su directorio, verá que este comando crea algunos archivos para usted. El conf.py contiene los valores de configuración y el index.rst sirve como la página de bienvenida de su documentación. El directorio de compilación albergará la documentación generada y Sphinx usa un Makefile (make.bat en Windows) para compilar la documentación.

Escribir documentación usando Sphinx

El archivo index.rst en la raíz de su directorio es la página de inicio de su aplicación. Entonces, ábralo con un editor de texto como VS Code, o cualquier otro buen editor de código gratuito—para editarlo.

Puede cambiar index.rst como mejor le parezca, pero una cosa que al menos debería tener es la directiva raíz toctree (árbol de tabla de contenido). Esto es esencial ya que conecta múltiples archivos a una sola jerarquía de documentos.

Para agregar documentación al archivo index.rst, puede usar el marcado RST.

Como ejemplo, considere un archivo index.rst para el módulo math_utils. Este archivo puede incluir una breve descripción general del propósito del módulo y una tabla de contenido que vincula a otras páginas de la documentación.

Bienvenido a Utilidades Matemáticas
.. árbol de toc::
 :máx. profundidad: 2
Empezando

Para utilizar este módulo, necesitará lo siguiente:
* Python instalado.
* Un editor de texto
Utilidades Matemáticas

El módulo `math-utils` proporciona funciones matemáticas básicas como sumas y
sustracción.

Puede agregar más archivos .rst según sea necesario. Por ejemplo, puede crear una guía de contribución en un archivo llamado contribucion.rst que contenga las siguientes pautas de contribución.

Guía colaboradora
Damos la bienvenida a las contribuciones a nuestro proyecto! Aquí hay algunas pautas para
contribuyendo:
- Bifurcar el proyecto en GitHub.
- Realice sus cambios en una nueva sucursal.
- Escribir pruebas para asegurarse de que sus cambios funcionan correctamente.
- Envíe una solicitud de incorporación de cambios con sus cambios.
- Realice los cambios solicitados.
¡Gracias por contribuir!

Luego puede vincular este archivo desde index.rst agregando una nueva sección a la directiva toctree:

.. árbol de toc::
 :máx. profundidad: 2
 :caption: Índice

 contribuyendo

Esto crea un nuevo elemento llamado contribución en la tabla de contenido que lleva al usuario a la página de contribución cuando se hace clic.

Una vez que haya escrito la documentación, el siguiente paso es construirla. Aquí, crear la documentación significa generar páginas HTML, manuales o PDF a partir de los archivos RST.

Construyendo la Documentación

Para crear la documentación con Sphinx, deberá ejecutar el comando make html en la raíz de su carpeta donde se encuentra el archivo MAKE.

hacer html

Debería ver los archivos HTML en la carpeta de compilación. Si hubo errores durante la compilación, Sphinx se lo hará saber en la terminal.

Para ver la documentación, abra el archivo index.html en su navegador:

Debería poder navegar a la guía de contribución desde la tabla de contenido.

Personalización de la documentación

En este momento, la documentación tiene un estilo básico. Si desea personalizarlo, agregando los colores de su marca o incluso agregando un modo oscuro, puede instalar y usar otros temas integrados o crea tu propio tema personalizado.

Para demostrarlo, intente cambiar el tema por el que se llama naturaleza:

1. Abra el archivo de configuración de Sphinx conf.py en el directorio de su proyecto Sphinx.
2. Busque la línea que define la opción html_theme y cámbiela a naturaleza
3. Guarde el archivo de configuración y reconstruya la documentación para ver sus cambios.

Este es el aspecto que debería tener la página de inicio de la documentación.

Si no desea utilizar los temas integrados, siempre puede utilizar un tema de esfinge de terceros en cambio.

Documentar su código usando Docstrings

Sphinx genera su documentación de Python a partir del texto que escribe en archivos RST. Si bien esto es suficiente en algunos casos, es posible que también desee utilizar docstrings en su código a nivel de módulo.

Las cadenas de documentos viven directamente dentro de los archivos fuente de su proyecto. Le permiten describir lo que hace el código, proporcionar ejemplos e incluso crear pruebas para esos ejemplos. Una vez que haya escrito cadenas de documentación, puede generar documentación a partir de ellas utilizando Sphinx.