--- author: Daniel A. Rodriguez date: 2025-10-12 --- # 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: ``` bash apt update && sudo apt upgrade -y ``` ------------------------------------------------------------------------ ## 2. Instalar dependencias necesarias Sphinx está basado en **Python**, por lo que necesitas tener instalado Python y `pip`: ``` bash 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. ``` bash python3 -m venv .venv source .venv/bin/activate ``` Instalamos Sphinx ``` bash 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: ``` bash 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: ``` bash 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: ``` bash 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: ``` bash 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 - Documentación oficial: - Tutorial de inicio rápido: ------------------------------------------------------------------------