Como Publicar La Documentacion De Tu Proyecto Python En Read The Docs

Por María Guerra Suárez y Ana Cáceres

Introducción

En nuestro día a día, colaboramos con un proyecto Python, el cual consiste en una librería que se quiere hacer open source. Tras varios meses de trabajo hemos llegado a la fase actual de publicación de la librería y nos vimos en la necesidad de publicar también la documentación que generamos con Sphinx. Después de un poco de investigación, nos dimos cuenta que la mayoría de las librerías de Python conocidas publican su documentación en Read the Docs. En este artículo vamos a explicar qué es Read the Docs, cómo funciona y vamos a dejar un ejemplo de cómo lo puede integrar en tu proyecto. Así que, vamos a comenzar.

¿Qué es Read the Docs?

Read the Docs es una plataforma donde podemos alojar documentación de manera gratuita para proyectos open source. La documentación se muestra bajo el dominio readthedocs.io en formato HTML aunque la plataforma también nos permite generarla en formato PDF.

Es importante recalcar que Read the Docs solo nos permite automatizar la generación de esta documentación si se usa Sphinx o Mkdocs. Pero, ¿cómo funciona esto realmente?

¿Cómo funciona?

Read the Docs se encarga de generar y publicar la documentación en tres etapas principales:

1. Obtiene el código fuente del proyecto, generalmente gracias a la integración con Github, Gitlab o Bitbucket.
2. Una vez obtenido el código fuente, Read the Docs levanta un contenedor de Docker donde utiliza Sphinx o Mkdocs para generar la documentación del proyecto en formato HTML o PDF si es especificado.
3. A continuación, Read the Docs verifica que la documentación se haya generado correctamente y que no haya errores o problemas.
4. Si se ha construido la documentación con éxito, ésta se publica automáticamente en un sitio web alojado por ellos.

Ahora que sabemos las fases que realiza la plataforma para llegar a publicar la documentación, vamos a ver como la podemos integrar en nuestro proyecto.

¿Cómo integrarlo en tu proyecto Python?

Si iniciamos sesión en Read the Docs con nuestro proveedor Git (Bitbucket en este caso), podemos conectar nuestro proyecto (que debe ser público) con esta plataforma. Así, cada vez que empujemos cambios a master, la documentación se actualizará automáticamente.

Una vez la sesión iniciada, necesitamos conceder acceso para leer el código fuente.

Después, tendremos que rellenar nuestro nombre de usuario y correo electrónico. Y, por último, nos saldrá una lista de los proyectos que tenemos en nuestro repositorio. Podemos importar cualquier proyecto pulsando la flecha que aparece a la derecha de su nombre.

Es importante que tengamos Sphinx instalado en nuestro proyecto. Aquí puedes ver cómo instalarlo.

Después de haber vinculado nuestro proyecto con Read the Docs, revisamos el fichero conf.py, que debería estar dentro de nuestra carpeta docs, y añadimos cualquier peculiaridad que deseemos que tenga nuestra documentación como la paleta de colores (html_theme), los autores del proyecto, el copyright, etc.

  
  # -- Project information -----------------------------------------------------
  # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
  
  project = 'Testing read the docs'
  copyright = '2023, Ana Caceres & Maria Guerra'
  author = 'Ana Caceres & Maria Guerra'
  
  # -- General configuration ---------------------------------------------------
  # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
  
  extensions = []
  
  templates_path = ['_templates']
  exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
  
  # -- Options for HTML output -------------------------------------------------
  # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
  
  html_theme = 'alabaster'
  html_static_path = ['_static']

Hay que tener en cuenta que el fichero conf.py debe estar en el mismo directorio que el index.rst. Si no es así, Read the Docs no podrá encontrar el fichero de inicio y dará un error al cargar la documentación (a no ser que especifiquemos el directorio en el que se encuentra ese fichero en la URL de la documentación). En nuestro caso, los ficheros .rst, que son generados por un script, se introducen en la carpeta docs/source. Por eso, en ese script añadimos la siguiente línea:

  copyfile("conf.py", Path("source", "conf.py"))

A continuación, creamos el fichero .readthedocs.yaml en el directorio raíz de nuestro proyecto. Este fichero nos permite añadir la configuración que necesita Read the Docs para generar la documentación de nuestro proyecto en concreto, como puede ser la versión de Python o paquetes específicos.

  # .readthedocs.yaml
  # Read the Docs configuration file
  # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
  
  # Required
  version: 2
  
  # Set the version of Python and other tools you might need
  build:
    os: ubuntu-22.04
    tools:
      python: "3.10"
    jobs:
      pre_build:
        - make doc
  
  # Build documentation in the docs/ directory with Sphinx
  sphinx:
      configuration: docs/source/conf.py

Existen muchas etiquetas que nos permiten configurar este fichero. En este caso hemos usado el **pre_build** para que nos cree los ficheros de la documentación con la estructura RST, es decir, que lance nuestro script.

Si subimos todos estos cambios a Bitbucket en la rama main, automáticamente se actualizará la documentación en Read the Docs y se publicará.

¿Cómo customizar la construcción de la documentación en Read the Docs?

Read the Docs ejecuta su propios comandos para generar la documentación. Si queremos customizar la construcción de nuestra documentación, tenemos que usar la etiqueta commands en el fichero .readthedocs.yaml:

    version: 2
    
    build:
      os: ubuntu-22.04
      tools:
        python: "3.10"
      commands:
        - pip install numpy
    		- make html
        - mkdir --parents _readthedocs/html/
    		- cp --recursive docs/build/* _readthedocs/html/

Esta etiqueta aún está en fase beta y debemos tener en cuenta que, cuando la usamos, no podemos añadir la etiqueta jobs.

Además, aún no está implementada la opción de instalar paquetes con apt-get al usar la etiqueta commands aunque ya hay una issue abierta en el proyecto para esto. Por ahora, sólo es posible instalar paquetes con pip dentro de esta etiqueta.

Esta limitación nos supuso un problema, ya que, para generar nuestra documentación, necesitábamos instalar el paquete sage y este aún no se puede instalar con pip. Por ello tuvimos que realizar un workaround en el que nosotras generamos la documentación HTML en local y la añadimos al repositorio. Esto desencadena la ejecución en Read the Docs para el que solo hemos configurado que copie nuestros archivos HTML ya generados dentro de la carpeta _readthedocs/html/, que es la carpeta que busca la plataforma a la hora de publicar la documentación en su dominio.

Probablemente si te surge un problema similar con alguno de tus paquetes puedas automatizar la generación del HTML mediante el uso de Github actions o Bitbucket pipelines y sus respectivas APIs para añadir esta documentación generada al repositorio y evitarte la generación manual. Este es el siguiente paso que queremos añadir a nuestro proceso de integración con Read the Docs.

Conclusión

Como podemos intuir, aunque Read the Docs nos puede llegar a facilitar mucho el trabajo de publicación de documentación, no es oro todo lo que reluce, también tiene sus limitaciones. Por esto, es importante recordar que debemos investigar como funcionan las herramientas que queremos integrar en nuestro proyecto para buscar la solución que mejor se adapte a nuestro problema.

Esperamos que este artículo te haya sido útil para entender como funciona Read the Docs, las funcionalidades existentes y las que están por llegar para su proceso de automatización de generación de documentación y que hayas podido publicar la documentación de tu proyecto Python en esta plataforma de forma exitosa.