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.