Skip to main content

Readthedocs

"Read the Docs" es una plataforma de documentación que facilita la creación, alojamiento y mantenimiento de documentación técnica de proyectos de software. Está diseñada para integrar con sistemas de control de versiones como Git y Mercurial, permitiendo que la documentación se genere automáticamente a partir del código fuente.

Aquí están algunas características clave de Read the Docs:

  1. Generación Automática de Documentación: La plataforma puede generar documentación automáticamente utilizando herramientas como Sphinx, que es muy popular para la documentación de proyectos en Python.

  2. Alojamiento de Documentación: Ofrece alojamiento gratuito para la documentación, lo que elimina la necesidad de configurar y mantener un servidor propio para este propósito.

  3. Versionado: Permite mantener múltiples versiones de la documentación, lo cual es útil cuando se necesita documentar diferentes versiones de un software.

  4. Integración con Control de Versiones: Se integra con repositorios de código en servicios como GitHub, GitLab y Bitbucket. Esto facilita la actualización automática de la documentación cada vez que se realizan cambios en el código.

  5. Internacionalización y Localización: Soporta la creación de documentación en múltiples idiomas, lo cual es beneficioso para proyectos con una audiencia global.

  6. Temas Personalizables: Ofrece una variedad de temas para la presentación de la documentación y permite la personalización de estos temas para ajustarse a las necesidades del proyecto.

En resumen, Read the Docs es una herramienta poderosa y conveniente para desarrolladores que buscan una solución eficiente y escalable para la documentación de sus proyectos.

Creación de la documentación​

Sphinx​

Sphinx es una herramienta poderosa para generar documentación en Python, y aunque su formato principal de entrada es reStructuredText (reST), es posible utilizar Markdown con algunas configuraciones adicionales. Aquí te explico cómo puedes hacerlo:

Instalación​

  1. Instala Sphinx y el soporte para Markdown: Necesitarás instalar Sphinx y algunas extensiones para soportar Markdown. Puedes hacerlo con pip:

    pip install sphinx recommonmark

    Además, si quieres soporte avanzado para Markdown, puedes instalar myst-parser:

    pip install myst-parser

Configuración del proyecto​

  1. Inicializa un proyecto de Sphinx: Si aún no tienes un proyecto de Sphinx, puedes inicializar uno con:

    sphinx-quickstart

    Esto te guiará a través de una serie de preguntas para configurar tu proyecto. Para propósitos básicos, puedes aceptar los valores predeterminados.

  2. Configura Sphinx para usar Markdown: Abre el archivo conf.py que Sphinx generó y añade las siguientes configuraciones:

    Para recommonmark:

    # conf.py

    # Agrega estas líneas para permitir el soporte de Markdown
    extensions = [
        'recommonmark'
    ]

    # Opcionalmente, añade estas configuraciones adicionales
    from recommonmark.transform import AutoStructify

    def setup(app):
        app.add_config_value('recommonmark_config', {
                'url_resolver': lambda url: github_doc_root + url,
                'auto_toc_tree_section': 'Contents',
                }, True)
        app.add_transform(AutoStructify)

    Para myst-parser:

    # conf.py

    # Agrega esta línea para usar myst-parser
    extensions = [
        'myst_parser'
    ]

    # Opcionalmente, configura MyST-Parser
    myst_enable_extensions = [
        "dollarmath",
        "amsmath",
        "deflist",
        "html_image",
        "colon_fence",
    ]

Creación de Documentación en Markdown​

  1. Crea archivos Markdown: Crea archivos .md en tu directorio de documentación. Por ejemplo, puedes crear un archivo index.md:

    # Bienvenido a la Documentación de Mi Proyecto

    Este es el archivo de inicio de la documentación.

    ## Sección 1

    Aquí va el contenido de la sección 1.

    ## Sección 2

    Aquí va el contenido de la sección 2.

  2. Referencia los archivos Markdown en tu archivo de índice: Asegúrate de que tu index.rst (o index.md si estás usando MyST-Parser) haga referencia a los archivos Markdown. Si estás usando index.rst, puedes hacerlo así:

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

       index.md

    Si estás usando index.md (con MyST-Parser), puedes referenciar otros archivos Markdown directamente:

    ```{toctree}
    ---
    maxdepth: 2
    caption: Contenido
    ---

    index.md
    otro_archivo.md

Generar la documentación​

  1. Genera la documentación: Ejecuta el siguiente comando para construir la documentación:

    make html

    Este comando generará la documentación en formato HTML en el directorio _build/html.

Mostrar la documentación​

Para revisar la documentación generada por Sphinx en un servidor local, puedes seguir estos pasos:

Paso 1: Generar la documentación HTML​

Primero, asegúrate de que has generado la documentación en formato HTML. Desde la raíz de tu proyecto de Sphinx, ejecuta:

make html

Esto generará la documentación en el directorio _build/html.

Paso 2: Servir la documentación localmente​

Puedes utilizar varios métodos para servir la documentación HTML localmente. Aquí te muestro algunas opciones comunes:

Opción 1: Usar Python's HTTP Server​

Python tiene un servidor HTTP incorporado que es muy fácil de usar. Desde la raíz del directorio _build/html, ejecuta:

cd _build/html
python -m http.server

Esto iniciará un servidor HTTP en el puerto 8000. Podrás acceder a tu documentación abriendo un navegador web y navegando a http://localhost:8000.

Opción 2: Usar live-server para recarga en vivo​

Si prefieres una experiencia de recarga en vivo (donde la página se actualiza automáticamente cuando realizas cambios en los archivos), puedes usar live-server. Primero, instala live-server usando npm:

npm install -g live-server

Luego, desde la raíz del directorio _build/html, ejecuta:

cd _build/html
live-server

Esto también iniciará un servidor HTTP, usualmente en el puerto 8080, y puedes acceder a tu documentación en http://localhost:8080. La ventaja de live-server es que recargará automáticamente la página cuando detecte cambios en los archivos.

Paso 3: Visualizar la documentación en el navegador​

Independientemente del método que hayas elegido, abre tu navegador y navega a la URL correspondiente (por ejemplo, http://localhost:8000 o http://localhost:8080). Deberías ver tu documentación generada por Sphinx.

Resumen​

  1. Genera la documentación HTML: make html.
  2. Inicia un servidor local:
    • Para un servidor básico: python -m http.server desde _build/html.
    • Para recarga en vivo: live-server desde _build/html.
  3. Accede a tu documentación: Abre http://localhost:8000 (o http://localhost:8080 si usas live-server) en tu navegador.

Estos métodos te permitirán revisar y verificar tu documentación localmente antes de publicarla.

Agregando otros temas​

Cambiar el tema de la documentación generada por Sphinx es un proceso sencillo. Sphinx viene con varios temas preinstalados, pero también puedes instalar y usar temas personalizados. A continuación, te explico cómo cambiar el tema de tu documentación.

Paso 1: Editar conf.py​

El archivo conf.py es donde configuras el tema de tu documentación. Abre conf.py y busca la variable html_theme. Aquí puedes establecer el tema que deseas usar.

Usar un tema preinstalado​

Sphinx incluye varios temas preinstalados, como alabaster (el tema por defecto), classic, sphinx_rtd_theme (el tema de la Documentación de Read the Docs), entre otros.

Por ejemplo, para usar el tema sphinx_rtd_theme:

  1. Instala el tema (si aún no está instalado):

    pip install sphinx-rtd-theme

  2. Edita conf.py y establece html_theme a sphinx_rtd_theme:

    # conf.py

    html_theme = 'sphinx_rtd_theme'

Usar un tema personalizado​

Si deseas usar un tema personalizado que no viene preinstalado con Sphinx, primero debes instalarlo. Hay muchos temas disponibles en PyPI. Por ejemplo, puedes instalar el tema sphinx_material:

  1. Instala el tema:

    pip install sphinx_material

  2. Edita conf.py y establece html_theme a sphinx_material:

    # conf.py

    html_theme = 'sphinx_material'

  3. Configura las opciones del tema (opcional):

    Muchos temas personalizados tienen opciones específicas que puedes configurar. Por ejemplo, para sphinx_material, puedes añadir configuraciones adicionales:

    # conf.py

    html_theme = 'sphinx_material'

    # Configuraciones del tema material
    html_theme_options = {
        'nav_title': 'Mi Proyecto',
        'color_primary': 'deep-purple',
        'color_accent': 'blue',
        'repo_url': 'https://github.com/tu_usuario/tu_repositorio',
        'repo_name': 'tu_repositorio',
        'globaltoc_depth': 3,
        'globaltoc_collapse': True,
        'globaltoc_includehidden': True,
    }

Paso 2: Añadir archivos estáticos y plantillas (opcional)​

Algunos temas permiten personalizar aún más la apariencia mediante el uso de archivos estáticos y plantillas personalizadas. Puedes colocar estos archivos en las carpetas _static y _templates respectivamente.

  1. Archivos estáticos: coloca archivos CSS, JS o imágenes personalizadas en _static.

  2. Plantillas personalizadas: coloca plantillas HTML personalizadas en _templates.

Paso 3: Reconstruir la documentación​

Después de hacer los cambios en conf.py, reconstruye la documentación para ver los cambios reflejados:

make html

Ejemplo completo de conf.py con sphinx_rtd_theme​

Aquí tienes un ejemplo completo de conf.py configurado para usar el tema sphinx_rtd_theme:

# conf.py

# -- Project information -----------------------------------------------------

project = 'Mi Proyecto'
author = 'Tu Nombre'
version = '1.0'
release = '1.0.0'

# -- General configuration ---------------------------------------------------

extensions = [
    'myst_parser',
]

# Configuración opcional para MyST-Parser
myst_enable_extensions = [
    "dollarmath",
    "amsmath",
    "deflist",
    "html_image",
    "colon_fence",
]

templates_path = ['_templates']
exclude_patterns = []

# -- Options for HTML output -------------------------------------------------

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

Resumen​

  1. Editar conf.py para cambiar el tema a uno preinstalado o personalizado.
  2. Instalar el tema (si es necesario).
  3. Configurar opciones del tema si el tema lo permite.
  4. Reconstruir la documentación para aplicar los cambios.

Siguiendo estos pasos, podrás cambiar y personalizar el tema de tu documentación generada por Sphinx de acuerdo a tus necesidades.

Publicar el código en Readthedocs​

Para subir tu documentación a Read the Docs en Python, sigue estos pasos:

  1. Prepara tu documentación:

    • Escribe tu documentación utilizando Sphinx, que es la herramienta recomendada para crear documentación en Read the Docs.
    • Asegúrate de tener un archivo de configuración conf.py y un archivo de índice index.rst en tu proyecto.

  2. Instala Sphinx: Si aún no tienes Sphinx instalado, puedes instalarlo utilizando pip:

    pip install sphinx

  3. Genera la documentación: Navega a la raíz de tu proyecto y ejecuta el comando sphinx-quickstart para configurar Sphinx. Sigue las instrucciones para crear los archivos iniciales necesarios.

    sphinx-quickstart

  4. Escribe tu documentación: Edita los archivos .rst en el directorio source generado por Sphinx. Aquí es donde escribirás la mayor parte de tu documentación.

  5. Configura tu proyecto en Read the Docs:

    • Crea una cuenta en Read the Docs.
    • Conecta tu cuenta de Read the Docs con tu repositorio (por ejemplo, GitHub, GitLab, Bitbucket) donde está alojado tu proyecto.
    • En Read the Docs, crea un nuevo proyecto y selecciona el repositorio que contiene tu documentación.

  6. Configura el archivo .readthedocs.yml: Coloca un archivo .readthedocs.yml en la raíz de tu repositorio para definir la configuración de construcción de Read the Docs. Un ejemplo básico podría ser:

    version: 2

    sphinx:
      configuration: docs/conf.py

    python:
      version: 3.8
      install:
        - requirements: docs/requirements.txt
    • version: Define la versión de configuración de Read the Docs.
    • sphinx.configuration: Indica la ruta al archivo de configuración conf.py de Sphinx.
    • python.version: Especifica la versión de Python a usar.
    • python.install.requirements: Especifica un archivo de requisitos donde defines las dependencias necesarias para construir tu documentación.

  7. Sube tu proyecto al repositorio: Asegúrate de que todos los archivos necesarios, incluidos los de configuración y documentación, estén en el repositorio. Luego, haz push a tu repositorio.

  8. Construye la documentación en Read the Docs: Una vez que tu proyecto esté configurado y enlazado con Read the Docs, cada vez que hagas un commit en tu repositorio, Read the Docs automáticamente reconstruirá y actualizará tu documentación.

  9. Revisa y ajusta:

    • Si hay errores, Read the Docs te mostrará registros detallados de la construcción donde puedes ver qué salió mal.
    • Ajusta tu configuración y los archivos de documentación según sea necesario y vuelve a hacer commit y push.

Aquí tienes una guía más detallada y específica en la documentación oficial de Read the Docs: Read the Docs: Introducción.