Generar documentación para los scripts de bash

Cuando empiezo algún script o un programa en python, se que lo voy a ir haciendo por fases y en cada momento me tengo que acordar de todo lo hecho con anterioridad.

Para todo esto es muy interesante generar documentación donde puedas retomar por donde ibas.

Parece algo sencillo, pero hay veces que me ha costado mucho reengancharme a lo que estaba haciendo, y como luego tengo que concentrarme en programar, pues se complica la cosa.

Escribiendo en archivos de texto como si fuera un diario he ido haciendo un seguimiento de mis pasos con los scripts, pero no me parece una solución elegante.

Es práctica, pero he estado buscando alguna solución que fuera más funcional.

Así que este artículo trata de buscar alguna manera de generar documentación a partir de los scripts que tengo en el ordenador.

Opciones encontradas

Esa inversión en tiempo cuando programas un script o algo más elaborado que soluciona un problema, queremos que esté identificado cada uno de sus pasos y su evolución.

Al cabo del día y con todas las actividades que realizamos esa parte del script donde lo dejamos un día, puede simplemente ser una laguna de memoria cuando lo volvamos a retomar.

Si a esto le sumas que programas habitualmente, entonces vas a necesitar alguna manera de generar documentación automáticamente para recordarte la funcionalidad que habías implementado.

Así que lo mejor es documentar dentro del código que hemos programado para luego a golpe de comando generar la documentación necesaria.

Una opción posible es usar RoboDoc con el que puedes insertar comentarios estilo C en el código Bash que generes y extraer la información necesaria.

Otra opción es utilizar otro script que se llama bashdoc que es un fronted que coge un archivo bash y crea una documentación en un formato específico. Este script funciona de manera similar a javadoc para los proyectos java, pero usando reStructuredText como lenguaje intermedio para generar el documento final.

Y por último otra de las opciones que he encontrado es usar TomDoc. Tomdoc es una especificación para generar documentación del código que escribes, que es fácilemente legible en archivos de texto plano, pero suficientemente estructurado para ser procesado y extraido por cualquier máquina. Este script nos extrae y genera la documentación de cualquier archivo bash que hayamos creado.

Para instalarlo en tu ordenador simplemente tienes que ejecutar los siguientes comandos:

$ git clone git://github.com/tests-always-included/tomdoc.sh.git
$ cd tomdoc.sh
$ make install

Una vez que lo tienes instalado el uso y las opciones son las siguientes:

Usage: tomdoc.sh [options] [--] [<shell-script>...]

            -h, --help              show help text
            --version               show version
            -t, --text              produce plain text (default format)
            -m, --markdown      produce markdown
            -a, --access <level>    filter by access level

    Parse TomDoc'd shell scripts and generate pretty documentation from it.

Resultados obtenidos

Haciendo pruebas con los distintos scripts y los archivos bash que tenía, ninguno de ellos me ha dado el resultado que estaba buscando.

No digo que sean malas soluciones sino que no era lo que estaba buscando.

Lo que si he pensado es que si no hay nada que realice este proceso entonces puedo hacer algo que se adapte a lo que busco. Por lo tanto una manera de implementar lo que busco es transformar los comentarios en archivos markdown que expliquen cada una de las partes del código y que además si lo necesito en algún momento me saque alguna función que tenga definida.

Para esto tengo que implementar un script personalizado, pero eso lo dejaré para otro artículo.

Conclusiones

Este proyecto se puede mantener gracias a la publicidad que tenemos en el.

Con todo esto puedo investigar, experimentar y probar todo lo que ves en los artículos que lees.

Recuerda que si te ha gustado lo que has leído puedes apoyar este proyecto a través de tus compras en Amazon, si, si, has leído bien, apoyar el proyecto. Con las compras que hagas de amazon me estarás ayudando a seguir haciendo este tipo de artículos.

Solo tienes que ir aquí y pegar la URL del producto de amazon que quieres comprar.

Tan simple como eso.

Y tan fácil.

Se feliz, y disfruta este día como si fuera una gran aventura.