Sphinx transforma archivos de texto e información del código en documentación navegable. Para un proyecto Python pequeño, el flujo es directo: instalar Sphinx, ejecutar sphinx-quickstart, escribir una introducción, habilitar autodoc, generar HTML y publicarlo. No hace falta comenzar con decenas de extensiones, un tema personalizado o una infraestructura compleja.

Esta guía crea una base mantenible para una biblioteca con layout src. Combina explicaciones escritas por personas con una referencia de API extraída de docstrings y type hints en Python.

Estructura e instalación

Partimos de esta estructura:

calculadora/
├── docs/
├── src/
│   └── calculadora/
│       ├── __init__.py
│       └── operaciones.py
├── tests/
└── pyproject.toml

Usa un entorno virtual e instala Sphinx. Instalar el propio paquete en modo editable permite a autodoc importarlo sin modificar sys.path en conf.py:

python -m pip install -e .
python -m pip install sphinx

Registra Sphinx entre las dependencias de documentación para que colaboradores y CI usen la misma gama de versiones. Según el gestor, puede ser un extra de pyproject.toml o un archivo breve docs/requirements.txt.

Crear la base con sphinx-quickstart

Ejecuta desde la raíz:

sphinx-quickstart docs

Elige separar los directorios de fuente y build, e indica nombre, autor, versión e idioma es. El comando crea, entre otros:

docs/
├── Makefile
├── make.bat
├── build/
└── source/
    ├── conf.py
    └── index.rst

Las preguntas pueden cambiar entre versiones; consulta el tutorial oficial de Sphinx. conf.py contiene configuración Python, index.rst es la página inicial y build/ recibe artefactos que normalmente no se versionan.

Mantén corta la configuración inicial:

## docs/source/conf.py
project = "Calculadora"
author = "Equipo Calculadora"
release = "1.0.0"
language = "es"

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
]

html_theme = "alabaster"

autodoc lee objetos Python. napoleon interpreta docstrings en estilos Google y NumPy. El tema Alabaster incluido basta para comenzar; adopta otro cuando exista una necesidad real.

Escribir docstrings que expliquen contratos

Las docstrings deben explicar intención, parámetros, retorno, excepciones relevantes y límites. No deben narrar cada línea de implementación. PEP 257 define convenciones básicas, como una frase de resumen y la organización de docstrings multilínea.

Con Napoleon, una función puede usar estilo Google:

def dividir(dividendo: float, divisor: float) -> float:
    """Divide dos números.

    Args:
        dividendo: Valor que se dividirá.
        divisor: Valor por el cual dividir. No puede ser cero.

    Returns:
        El cociente de ambos valores.

    Raises:
        ValueError: Si ``divisor`` es cero.
    """
    if divisor == 0:
        raise ValueError("el divisor no puede ser cero")
    return dividendo / divisor

Las anotaciones comunican tipos y la docstring comunica semántica. Evita duplicar tipos si la página ya muestra type hints; documenta significado, unidades, condiciones y efectos secundarios. Las docstrings públicas deben acompañar los cambios de comportamiento igual que las pruebas con pytest.

Generar la referencia con autodoc

Crea docs/source/api.rst:

Referencia de API
=================

Operaciones
-----------

.. automodule:: calculadora.operaciones
   :members:
   :undoc-members:
   :show-inheritance:

Incluye la página en index.rst:

Calculadora
===========

Biblioteca pequeña para operaciones matemáticas previsibles.

.. toctree::
   :maxdepth: 2
   :caption: Contenido

   uso
   api

Crea además uso.rst con instalación, un ejemplo mínimo y el comportamiento esperado. La API generada responde “¿qué objetos existen?”; la explicación narrativa responde “¿cómo completo una tarea?”. Ninguna sustituye a la otra.

Durante el build, autodoc importa calculadora.operaciones, así que también ejecuta el código en el nivel superior del módulo. Evita conexiones de red, lectura obligatoria de secretos e inicializaciones costosas al importar. Si falta una dependencia opcional, autodoc_mock_imports = ["dependencia"] puede desbloquear el build, pero simular tu propio paquete ocultaría errores auténticos.

Consulta la referencia oficial de autodoc antes de añadir opciones a la directiva; explica importaciones, selección de miembros y orden de presentación.

Generar HTML y fallar ante warnings

Desde la raíz, ejecuta:

sphinx-build -M html docs/source docs/build

Abre docs/build/html/index.html. Durante el desarrollo, make -C docs html o docs\make.bat html ofrecen atajos equivalentes creados por quickstart.

En CI, convierte los warnings en fallos para detectar referencias rotas y docstrings incorrectas:

sphinx-build -W --keep-going -b html docs/source docs/build/html

-W trata los warnings como errores y --keep-going recopila más problemas antes de terminar. Actívalo cuando la documentación aún es pequeña. Esperar a tener cientos de páginas dificulta mucho la limpieza. No silencies categorías completas sin entender primero la causa.

Errores frecuentes son olvidar instalar el paquete, dejar una página fuera del toctree, indentar mal una directiva RST e importar módulos con efectos secundarios. Otro error es generar toda la API sin crear una guía de uso. La documentación debe ayudar a resolver una tarea real, no limitarse a enumerar firmas.

Publicar con Read the Docs

Read the Docs clona el repositorio, instala dependencias y ejecuta Sphinx. Añade .readthedocs.yaml en la raíz:

version: 2

sphinx:
  configuration: docs/source/conf.py
  fail_on_warning: true

python:
  install:
    - method: pip
      path: .
    - requirements: docs/requirements.txt

Declara en docs/requirements.txt la gama de versiones de Sphinx admitida. Después importa el repositorio en el servicio y revisa el log del primer build. El tutorial oficial de Read the Docs explica el proceso y la configuración vigente.

Como alternativa, añade el comando estricto al pipeline explicado en la guía de GitHub Actions para Python y publica docs/build/html en tu hosting estático. Evita mantener dos mecanismos sin necesidad: elige Read the Docs o la CI existente como responsable principal.

Enlaces, inventarios y versiones

Las referencias internas deberían usar roles de Sphinx en lugar de URLs relativas cuando sea posible. Una etiqueta explícita como .. _instalacion: permite enlazar una sección con :ref:\instalacion`aunque el archivo fuente cambie de lugar. Para objetos Python documentados, roles como:class:y:func:` crean enlaces y permiten que el build detecte nombres incorrectos.

Intersphinx conecta la documentación con inventarios publicados por otros proyectos, incluida la biblioteca estándar de Python. Habilita sphinx.ext.intersphinx, configura solo fuentes fiables y comprueba que las referencias se resuelvan durante el build. Es una solución más mantenible que copiar explicaciones externas o conservar enlaces profundos a mano.

Si hay varias versiones públicas de la librería, indica qué documentación corresponde a la versión estable y cómo consultar versiones anteriores. Read the Docs puede conservar builds por tag; un hosting propio necesita una estructura de URLs definida en CI. No publiques automáticamente la documentación de la rama principal como si describiera el último paquete estable. Mostrar funciones aún no publicadas sin una advertencia visible confunde a quien instaló la versión disponible.

Mantenimiento sin burocracia

Actualiza documentación y código en el mismo cambio. Al modificar una función pública, revisa su docstring, la página de uso y la prueba relacionada. Una revisión de pull request puede comprobar tres cosas: el ejemplo aún funciona, la firma generada coincide con la API y el build no emite warnings. Esta rutina breve evita una gran limpieza posterior.

No intentes documentar cada función privada. Prioriza instalación, el primer resultado útil, decisiones que sorprenden al usuario e interfaces públicas. Los ejemplos deben ser suficientemente pequeños para entenderse de forma aislada y suficientemente completos para ejecutarse. Si un fragmento requiere archivos o variables de entorno, indícalo antes del código. Elimina páginas obsoletas en vez de conservarlas para aumentar volumen: encontrar instrucciones antiguas es peor que no encontrar ninguna página.

Lista de comprobación y conclusión

  • Instala el paquete y Sphinx en un entorno aislado.
  • Ejecuta sphinx-quickstart docs y mantén conf.py enfocado.
  • Habilita autodoc y napoleon porque el proyecto los utiliza.
  • Escribe docstrings públicas con contratos, retornos y excepciones.
  • Combina una guía de uso con la referencia automática de API.
  • Genera HTML localmente y corrige todos los warnings.
  • Ejecuta sphinx-build -W --keep-going en CI.
  • Publica mediante Read the Docs o un único flujo de CI.

Un inicio saludable es pequeño: una portada, una página de uso y una referencia de API. Cuando usuarios reales necesiten búsquedas mejores, versiones o formatos adicionales, Sphinx puede crecer con el proyecto. Hasta entonces, el contenido correcto y un build fiable aportan más que una gran colección de extensiones.