Instalación

Esta guía describe paso a paso cómo instalar Sphinx, una herramienta para generar documentación profesional en múltiples formatos, incluyendo HTML, PDF y ePub.

1. Actualizar el sistema

Antes de instalar cualquier paquete nuevo, se recomienda actualizar los repositorios y paquetes existentes:

apt update && sudo apt upgrade -y

2. Instalar dependencias necesarias

Sphinx está basado en Python, por lo que necesitas tener instalado Python y pip:

apt install -y python3 python3-pip

3. Instalar Sphinx

Antes de hacer cualquier instalación con pip lo recomendable es iniciar un entorno virtual. De esa manera aislamos dependencias y evitamos conflictos.

python3 -m venv .venv
source .venv/bin/activate

Instalamos Sphinx

pip install sphinx

⚠️ Cada vez que ejecutemos sphinx será necesario iniciar el entorno virtual previamente.

4. Verificar la instalación

Comprueba que Sphinx se haya instalado correctamente:

sphinx-build --version

Si ves un mensaje similar a sphinx-build X.Y.Z, la instalación fue exitosa.

5. Crear un nuevo proyecto de documentación

Para generar la estructura base de un proyecto:

sphinx-quickstart

Sigue las instrucciones interactivas para configurar el proyecto. Esto creará un conjunto de archivos en un nuevo directorio.

6. Construir la documentación

Una vez configurado, puedes generar la documentación HTML con:

make html

Los archivos resultantes se encontrarán en el directorio _build/html.

7. (Opcional) Instalar extensiones útiles

Algunas extensiones comunes para mejorar tu documentación:

pip install sphinx-rtd-theme myst-parser sphinx-autobuild

  • sphinx-rtd-theme → Tema usado por Read the Docs

  • myst-parser → Permite usar Markdown (.md) en lugar de reStructuredText (.rst)

  • sphinx-autobuild → Regenera la documentación automáticamente mientras editas

8. Recursos adicionales