Recipes For Linux

Instalación y primeros pasos con Sphinx

Sphinx Autodoc

Sphinx Autodoc

En el artículo de hoy quiero enseñaros como se realiza la instalación y primeros pasos con Sphinx. Sphinx es una potente herramienta de documentación de software que nos permite generar múltiples tipos de salidas, por ejemplo, mostrar toda la documentación como página web. Además haciendo uso de algunos de sus módulos como el módulo de Autodoc, podremos utilizar los comentarios escritos en le propio código (docstrings) para que la documentación se genere sola.

Tan sólo es necesario configurar un par de parámetros y podremos documentar nuestro software como profesionales.

Sphinx fue creada originalmente para documentar código en Python, que es el ejemplo que veremos hoy, pero se podría utilizar para documentar otros lenguajes de programación.

Instalación

La instalación es sencilla en un sistema unix como ubuntu. En terminal debemos ejecutar

o

Para más información sobre la instalación o cómo instalar en otras distribuciones podéis consultar la documentación oficial de Sphinx.

Configuración

Una vez instalado debemos generar el directorio de documentación y esto nos llevará a configurar los parámetros básicos de Sphinx.

Para ello, en el directorio raíz donde se encuentra el software que queremos documentar debemos ejecutar:

Esto iniciará un proceso de preguntas y opciones que debemos ir contestando. En la mayor parte de los casos sólo tendrás que pulsar ENTER ya que viene con valores predefinidos.

Eso sí, tendrás que prestar especial atención ante las siguientes preguntas:

  • Root path. O lo que es lo mismo, directorio raíz donde quieres alojar la documentación. Puedes crear un subdirectorio docs dentro de tu directorio de software para mantener todos los ficheros de documentación separados de los de código.
  • autodoc. Muy importante activar esta opción que de forma predeterminada viene desactivada. Con ella podremos usar los docstring del código para generar automáticamente la documentación.
  • Asegúrate de generar un makefile. Esto siempre ayuda.

Una vez configurado todo podemos comprobar que el módulo de autodoc está activo visualizando el fichero conf.py. Dentro debemos ver la siguiente extensión insertada:

Ahora para generar la documentación solo debemos hacer el make con el parámetro de salida, en nuestro caso, como queremos una pagina web, será html, de esta forma

Ahora si accedemos a

veremos la página índice de nuestra documentación. Como podemos ver es muy básica y estará prácticamente vacía.

Antes de rellenarla de contenido vamos a cambiar el theme de la documentación para hacerla más parecido a las típicas páginas de ReadTheDocs. Para ello, si no lo tenemos instalado, debemos instalar el theme de ReadTheDocs:

Ahora debemos cambiar esta opción en el fichero de configuración conf.py. Para ello comentamos el theme en uso y lo cambiamos por el nuevo theme: sphinx_rtd_theme

Autodocumentación

Uno de los módulos más interesantes de Sphinx es el autodoc, que nos permite generar documentación automática a partir de los docstrings del código.

En python, estos docstrings son aquellos bloques de texto dentro de triples comillas que aparecen justo después del nombre de la clase, o función. Por ejemplo:

Una vez más para poder hacer funcionar el módulo de autodoc debemos comprobar o modificar el fichero de configuración conf.py. Al inicio del fichero debemos insertar el PATH donde se encuentra el código a escanear en busca de documentación.

Añadir módulos a documentar

Todos los módulos que queremos documentar, ya sea un módulo completo, una clase concreta, o una función, se añaden en ficheros *.rst. El fichero inicial es el index.rst que es el que estamos viendo en la web, un fichero que tendrá más o menos esta pinta:

Una de las cosas importantes de este fichero es que es dependiente de la tabulación al igual que Python. Por tanto si no funciona como esperas, revisa esas tabulaciones.

Para añadir otro módulo, solo tendremos que añadir una linea a ese fichero que apuntará a otro fichero *.rst, en este caso a ejemplo.rst

Y en ejemplo.rst tendremos el siguiente contenido:

Con este contenido dentro de ejemplo.rst lo que hacemos es que se documenten todas las clases y funciones del fichero de código llamado, en este caso, ejemplo.py.

Ahora podemos hacer

Y nos debería generar la documentación completa de todas nuestras funciones y clases.

Si no es así, siempre podemos hacer uso del comando sphinx-apidoc que nos generaría el fichero ejemplo.rst de forma automática.

Por último, si por ejemplo queremos generar como documentación el docstring del __init__ de las clases pondremos en el fichero de configuración conf.py

Y listo, ya podemos documentar todos nuestros proyectos python.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *