Documentación con Sphinx en Python

Documentación con Sphinx en Python

Sphinx es una herramienta de generación de documentación para software, escrita en Python. Es una herramienta muy flexible que permite crear documentación en diferentes formatos, como HTML, PDF, EPUB, etc.

En este tutorial, veremos cómo crear documentación para un proyecto Python utilizando Sphinx.

Requisitos

Para seguir este tutorial, necesitas tener Python 3 instalado en tu sistema. También necesitarás instalar Sphinx. Puedes instalarlo con el siguiente comando:

pip install sphinx

Creación de un proyecto

Lo primero que tenemos que hacer es crear un proyecto Sphinx. Para ello, creamos un directorio para nuestro proyecto y lo activamos:

mkdir mi_proyecto
cd mi_proyecto

Ahora, podemos generar la estructura de archivos de Sphinx con el siguiente comando:

sphinx-quickstart

Este comando nos preguntará una serie de preguntas para configurar nuestro proyecto. Las respuestas por defecto son adecuadas para la mayoría de los casos.

Una vez que hayamos generado la estructura de archivos, podemos empezar a escribir la documentación.

Escribir la documentación

La documentación de Sphinx se escribe en reStructuredText, un lenguaje de marcado ligero. Para escribir una página de documentación, creamos un archivo con la extensión .rst.

Por ejemplo, para crear una página de documentación para la función sum(), creamos el siguiente archivo:

.. code-block:: python

def sum(a, b):
    """
    Suma dos números.

    Args:
        a (int): El primer número.
        b (int): El segundo número.

    Returns:
        int: La suma de los dos números.
    """

    return a + b

Este archivo contiene la definición de la función sum(), junto con una documentación que explica su funcionamiento.

Para incluir el código de la función en la documentación, utilizamos la etiqueta .. code-block:: python. Esta etiqueta crea un bloque de código que se formateará correctamente.

Para escribir una página de documentación para un módulo, creamos un archivo con la extensión .rst en el directorio del módulo.

Por ejemplo, para crear una página de documentación para el módulo math, creamos el siguiente archivo:

.. toctree::
    :maxdepth: 2

    math.sqrt
    math.sin
    math.cos

Este archivo contiene una lista de las funciones y variables del módulo math.

Generando la documentación

Una vez que hayamos terminado de escribir la documentación, podemos generarla con el siguiente comando:

make html

Este comando generará una página web con la documentación de nuestro proyecto.

Podemos abrir la página web en un navegador para verla.

Extensiones de Sphinx

Sphinx ofrece una serie de extensiones que permiten añadir funcionalidades adicionales a la documentación. Algunas de las extensiones más populares son:

• autodoc: Genera documentación automática para los módulos y funciones de Python.
• doctest: Incluye ejemplos de código con sus resultados en la documentación.
• mathjax: Permite insertar fórmulas matemáticas en la documentación.

Para utilizar una extensión, debemos añadirla a la lista de extensiones en el archivo conf.py.

Conclusión

Sphinx es una herramienta muy potente y versátil para crear documentación de software. Con un poco de práctica, podemos crear documentación de alta calidad para nuestros proyectos Python.

Ejercicios

• Crea una página de documentación para una clase Python.
• Utiliza la extensión autodoc para generar documentación automática para un módulo Python.
• Utiliza la extensión doctest para incluir ejemplos de código con sus resultados en la documentación.

Recursos adicionales

• Documentación oficial de Sphinx: https://www.sphinx-doc.org/en/master/
• Tutorial de Sphinx: https://www.sphinx-doc.org/en/master/tutorial/
• Guía de extensiones de Sphinx: https://www.sphinx-doc.org/en/master/usage/extensions/index.html