Generar de manera automatica la documentacion de nuestros Shell Scripts

Si eres desarrollador, documentar es siempre muy importante (es un rollo, pero es importante), y no solo porque es casi seguro que luego tu codigo sea mantenido por otra persona, si no porque pasa el tiempo y seguramente ni recuerdes porque hiciste esa funcion de esa manera o de otra. Esta semana yo me enfrentaba a un problema. Tengo implementadas mas de 40 funciones en shell script para hacer determinadas acciones como pueden ser: recoger ficheros por FTP desde maquinas remotas, matar procesos o ejecutar consultas a oracle mediante sqlplus. Esas funciones estan implementadas en un API para que el resto de usuarios las empleen en sus scripts. Pero es lo que pasa siempre, si no estan documentadas, la gente suele pasar de leerlas e incluso usarlas. Asi que me decidi buscar algun metodo “sencillo” que me permitiera documentar mis shell scripts y hacer accesible esa documentacion al resto.

Cuando programo en Java, documentar es sencillisimo, Para no olvidarme yo suelo emplear el plugin JAutoDoc que si incluso la ocasion lo requiere y no he puesto ningun comentario en el codigo, el se encarga de ver que funciones estan sin comentar y añade los comentarios de manera automatica. Despues exportar esa informacion a un HTML es invocar a JDoc y ya está. Pero claro, esto me funciona para codigo Java, no para scripts en bash.

Asi que empece a buscar alternativas y encontre algunas que me parecieron interesantes, aunque no me llegaran a servir para mis propositos:

* Vi JSDoc, que es ideal si tienes que documentar codigo Javascript. Consiste al igual que en JDoc, escribir los comentarios de las funciones de acuerdo a una sintaxis especial y entonces luego un parser se encarga de generar el HTML correspondiente con la descripcion de las funciones y metodos.

No me sirve, es para JavaScript y no parsea mis shell scripts. Continue buscando y evalue herramientas como Doxygen (que es una tool fantastica para documentar codigo en diferentes lenguajes), BashDoc e incluso ScriptDoc que es usado por IDEs como Aptana para generar la documentacion internamente (video de su funcionamiento). Este ultimo tampoco me sirvio, pues anda mas enfocado a javascript.

Al final me quede con dos: Robodoc y Natural Docs, que llevan soporte de shell script. Robodoc es una aplicacion para Windows (podria probar a ejecutarla con wine), asi que me decante por “Natural Docs“.

Natural Docs es una herramienta open source para generar documentacion que soporta multiples lenguajes de programacion (por defecto mas de 19, entre los que se incluyen Java, C++, PLSQL, JavaScript, ADA, etc…) y lo mejor de todo, Si nuestro lenguaje no esta contemplado podemos escribir un parser a medida para poder interpretarlo. Chachi!!!

En nuestro caso no hay problemas pues para parsear ficheros de Shell script, podriamos usar por ejemplo el parser de Ruby (que ya va incluido por defecto). Mi truco, renombras de .sh a .rb, ejecutas el parser y ya tienes la documentacion.
La idea es simple. al igual que JSDoc tienes que escribir los comentarios de tu codigo de una manera especial y luego esa informacion sera usada por el parser para generar de manera automatica la documentacion en formato HTML.

Por ejemplo vamos a documentar el siguiente trozo de codigo en bash llamado “funciones.rb”:

#!/bin/bash

#=============================================
# Function: matar_proceso
#
# Mata el proceso con el nombre especificado
#
# Parameters:
#
# $1 - Nombre o PID del proceso.
#
#=============================================
function matar_proceso()
{}

#=============================================
# Function: ejecutar_sql
#
# Ejecuta una consulta SQL mediante sql*plus
#
# Parameters:
#
# $1 - Usuario de la base de datos.
# $2 - Password de la base de datos.
# $3 - SID de Oracle.
# $4 - Consulta a ejecutar.
# $5 - Fichero donde dejar los resultados.
#
# Returns:
#
# codigo de estado - El estado de la operacion
#
# Ejemplo de codigo:
# > $ ps -ef | grep oracle
#
#===============================================

function ejecutar_sql()
{
	echo "No hago nada, pero te imaginas que hago cosas"
}

Para generar la documentacion, tras descargar y descomprimir el zip de NaturalDocs, ejecutariamos:

jose@soledad:~/Escritorio/NaturalDocs-1.4$ perl NaturalDocs -i ./otarget -o HTML ./html -p ./ptarget
Finding files and detecting changes...
Parsing 1 file...
Building 1 file...
Building 3 indexes...
Updating menu...
Updating CSS file...
Done.

Donde con -i indicamos el directorio que contiene el proyecto que contiene el codigo que queremos documentar, -o indica el formato de salida que queremos (HTML) y donde dejaremos esos ficheros generados y -p es un directorio temporal de proyecto necesario para que se ejecute correctamente NaturalDocs.

El resultado de ejecutar el comando anterior ya seria una lista de ficheros HTML con la documentacion extraida de nuestros shell script, documentacion por la que ya podemos navegar, como podeis observar en la imagen que encabeza el articulo.
Si vuelves a editar los shell scripts y cambian, no pasa nada, vuelves a ejecutar el parser y la documentacion generada se actualiza.

Enlace | NaturalDocs

1 Response to “Generar de manera automatica la documentacion de nuestros Shell Scripts”


  1. 1 manu enero 14, 2009 en 7:59 pm

    Holas, robodoc no es una aplicacion exclusivamente para windows, no necesitas wine para instalarla en ubuntu… de hecho esta en los repositorios d synaptic.


Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

Conectando a %s







¿Es compatible tu equipo con Ubuntu?


( Muchos fondos de pantalla, aqui )

DESCARGATE SCIFI LIFE

365 Dias de Soledad
Me debes los sueños, las promesas y las noches rotas. Me debes la paz, la sonrisa y la esperanza robadas. Me debes la sangre, las lágrimas y el sudor vertido. Me debes las noches vacías, los abrazos anhelados. Me debes un beso de ajenjo de tu amarga boca.

The Ubuntu Counter Project - user number # 11961
Geo Visitors Map
agosto 2008
L M X J V S D
« Jul   Sep »
 123
45678910
11121314151617
18192021222324
25262728293031

Blog Stats

  • 30.702.318 hits

A %d blogueros les gusta esto: