Cómo automatizar la documentación en python con Sphinx + ejemplo de IA

Lo fácil que es documentar y todos sabemos que no lo harás.

Pero bueno, no pasa nada, porque puedes automatizarlo, que es lo que todos los grandes programadores hacen.

¿Quién?

Tú

¿Cuando?

Ahora

¿Cómo?

Con este artículo

¿Por qué?

Por quedar bien, tampoco vamos a mentir.

A quien escribe bien le entienden y, al que no, le pasan Pylint

Todo lenguaje de programación tiene su estándar. Esto es importante para seguir una estructura que permita una fácil lectura del código y la máxima compatibilidad con diferentes sistemas.

Por ejemplo, hay lenguajes que escribirán las funciones como

“nueva_funcion()”

Con todo minúscula y separando las palabras con guion bajo. Otros, como

“nuevaFuncion()”

Todo junto y a las palabras nuevas se les pone la primera letra en mayúscula.

Pero no puede haber programas que nombren a sus funciones simultáneamente como

“nueva_funcion1()” y,

“nuevaFuncion2()”

Esto sería complicado de leer, un caos de código que lía y además no queda estético.

Va a funcionar porque no son errores semánticos ni sintácticos del lenguaje, pero eso no implica que el código sea fluido y esté bien hecho. Así que, para eso, cada lenguaje tiene un estándar que el programador debe seguir.

En el caso de python, tenemos un analizador de código que puntúa tus habilidades como programador.

¿Preparado para el examen?

Se llama pylint, y para instalarlo basta con el siguiente comando

>> pip install pylint

Se ejecuta como si fueras a ejecutar tu código normal.

>> pylint muestra.py

Aquí un ejemplo

Como ves este código está horrible. Se han llamado a unas librerías que no usas en ningún momento, falta la línea en blanco final, no tienes incluido ningún docstring…

Solucionamos estos problemillas y… voilá

Nuestro código está perfecto.

Así, con pylint, podemos detectar muchas cosillas que, aunque podamos compilar y cumplan con las funcionalidades del programa, pueden causar caos a la larga.

Pero espera, repite eso del docstring

Muy buena pregunta porque con ello generaremos nuestra documentación.

Así, resumiendo, un doctring es un comentario de tu código y se hace usando tres comillas

“”” Hola, esto es un docstring para explicar mi código. ”””

Como mínimo debe haber uno, pero acostúmbrate a tener uno por cada función.

Todas las funciones en python tienen asociado un docstring y, se puede visualizar con la extensión .doc.

Por ejemplo, la funcion print().

Si tu tienes el siguiente código

Y lo ejecutas, lo que haces es imprimir el comentario de la función print() de python.

Esto además es muy cómodo para conseguir rápidamente la documentación de cualquier función en python.

Pero también lo puedes hacer en todas tus propias funciones. Por ejemplo, el siguiente código

Te imprimiría el comentario de tu propia función

Esto no solo lo puedes hacer con funciones, sino con los propios scripts. Si hago un script llamado muestra.py al que le he incorporado un doctring, puedo llamarlo en otro archivo y conseguir su comentario.

Así, esto daría

Hemos topado con la Santa Estandarización

¿Te acuerdas que había un estándar que seguir a la hora de escribir tu código?

Pues también lo hay a la hora de comentarlo.

Cuando comentas una función, generalmente tienes que poner lo siguiente:

“””” summary: descripción de la función.

Args:

:param (type): descripción de los parámetros de entrada y de qué tipo de variable se trata

Returns:

:return: descripción de los parámetros que retorna la función

Error:

:throws: descripción de la gestión de errores (try… Exception…)

“”””

Pero si no te apetece escribirlo todo, no te preocupes porque en visual estudio hay una extensión que se llama autoDocstring, en el que tú seleccionas el código dentro de la función y automáticamente te genera la estructura de tu comentario.

Imagina que tienes este código:

Al escribir las tres comillas, debajo de la función, te aparecerá la opción “Generate Doctring” o, en su defecto, clica botón derecho y selecciona “Generate Doctring”. Esto te generará la siguiente estructura automáticamente en formato Google Docstrings:

Y ya solo tendrás que modificarlo a tu gusto.

¿No quieres pensar la descripción que le vas a poner a tu función?

No pasa nada porque existe otra extensión llamada mintlify doc writer que lo hará por ti usando la inteligencia artificial.

Selecciona tu código, vete a la extensión y clica sobre Generate docs, te creará lo siguiente en formato reST

De momento, ni siquiera has tenido que escribir nada y ya tienes la mitad de tu documentación hecha.

Deseo, deseo… una página web explicando mi código

Querida, los deseos se cumplen, no te preocupes.

Para esto vamos a utilizar Sphinx

Primero los instalamos

>>pip install sphinx

Seamos sinceros, el tema que trae por defecto no es muy bonito que digamos y, puestos a hablar de estética de tu código, cambiémoslo. Puedes escoger otro en este enlace. Nosotras, instalaremos el siguiente:

>> pip install sphinx-rtd-theme

Por pasos

1. Crea una carpeta llamada doc. Ahí es donde guardaremos toda nuestra documentación.
2. Métete dentro >>cd doc.
3. Ejecuta el siguiente comando: >>sphinx-quickstart.

Esto preguntará por el nombre del proyecto, el o las autoras, la release version y el idioma de la documentación. En este caso hemos seleccionado lo siguiente.

5. Vete otra vez a la carpeta princpal >> cd ..

6. Ejecuta lo siguiente >>sphinx-apidoc -o doc . el comando sphinx-apidoc que te generará el árbol de la documentación en doc de los archivos que tengas en el directorio actual “.”

Es decir, lo siguiente

7. Abre el archivo index.rst y añade modules al toctree (modules es el documento que llama al resto de rst generados por cada script que haya)

index.rst

modules.rst

8. Abre conf.py y modifica con los siguientes datos:

Añade lo siguiente para que la búsqueda vaya en orden.

import os

import sys

sys.path.insert(0, os.path.abspath(“..”))

En extensions, por las siguientes: “sphinx.ext.todo”, “sphinx.ext.viewcode”, “sphinx.ext.autodoc”

sphinx.ext.autodoc: es el más importante ya que incluirá la documentación directamente de tus comentarios.

sphinx.ext.viewcode: esto incluirá el código en la documentación

sphinx.ext.todo: recomendable, ya que soporta elementos todo

Finalmente, añade el tema que nos descargamos anteriormente html_theme = ‘sphinx_rtd_theme’

9. Entra en la carpeta doc de nuevo >>cd doc

10. Ejecuta >>make.bat html

Esto generará todo el árbol de documentación en formato html (el formato lo puedes elegir, pero por ahora nos quedaremos con html).

Si ahora vas a la carpeta ./doc/build puedes abrir index.html que te dará la siguiente página.

Aquí aparece el nombre de tu proyecto, puedes ver el código, puedes buscar funciones y puedes ver toda la estructura explicada.

Por ejemplo, podrías ir al módulo asociado al script muestra2.py y ver qué es lo que hace la función multiplica() que hemos creamos anteriormente

Si le das a source, también podrás ver el código directamente

Listo, sin escribir prácticamente nada, hemos generado la documentación para el desarrollador.