Para la formalización de ciertos proyectos, se pide «redactar» un manual de código en el que aparezcan todos los ficheros que componen la aplicación.
Si utilizáis LaTeX, he creado un script que te permite crear el manual de código de la aplicación con sólo llamarlo con los parámetros adecuados.
Deciros que el esqueleto del script, la parte que recorre directorios y ficheros, está basado en el script Arbol de directorios de Paco Debian.
El código del script es el siguiente:
- #!/bin/bash
- #set -e
- #set -u
- #set -x
- func_ficheros()
- {
- listaficheros=$(find -maxdepth 1 -type f -iname "*."$extpar | sort) # extraer lista ordenada de ficheros del directorio actual
- for item in $listaficheros # recorrer lista de ficheros
- do
- extfich=${item##*.} # obtener extension del fichero
- if [ $extfich = $extpar ] # si la extension es la misma que especificamos en $2
- then
- fichero=${item##*"./"} # eliminar todos los "./" que coloca find
- fichero=${fichero//"_"/"_"} # reemplazar todos los "_" por "_", LaTeX trata "_" como error
- echo "section{Fichero "$fichero"}" # creamos la seccion con el nombre del fichero
- echo -e "lstinputlisting{"$PWD"/"${item##*"./"}"}n" # incluimos el fichero con ruta completa y con "_" porque es ruta fisica
- fi
- done
- }
- func_recursiva()
- {
- for OBJ in * # recorrer el directorio $1
- do
- (
- if [ -d "${OBJ}" ] # es un directorio
- then
- cd "${OBJ}" # cambiar a este directorio
- var=$(find -maxdepth 1 -type f -iname "*."$extpar | wc -l) # ver si hay en el directorio actual ficheros de tipo $2
- if [ $var != "0" ] # si hay ficheros de tipo $2
- then
- nombrecarpeta=${PWD##*$raiz_pwd} #extraer solo el nombre de la carpeta
- carpeta=${nombrecarpeta//"_"/"_"} # reemplazar todos los "_" por "_", LaTeX trata "_" como error
- echo -e "n" # retorno de carro
- echo "chapter{Carpeta "$dirpar$carpeta"}" # crear nueva subseccion con esta subcarpeta
- func_ficheros # procesar los ficheros de este directorio
- fi
- func_recursiva # seguir mirando subcarpetas
- fi
- )
- done
- }
- #################
- # INICIO #
- #################
- if [ $# != 3 ] # control de errores - utilizar los tres parametros: nombrecarpeta, extensionfichero y ficherolatex
- then
- echo -e "ERROR: Incorrecto numero de argumentosn"
- echo "Uso del programa: ./myscript nombrecarpeta extensionfichero ficherolatex"
- echo "Ejemplo: ./myscript micarpeta php codigo.tex"
- exit 0
- fi
- dirpar=$1 # obtener el parametro de carpeta raiz, en func_recursiva se pierde la visibilidad del parametro
- extpar=$2 # obtener el parametro de extension a buscar, en func_recursiva se pierde la visibilidad del parametro
- exec 1>$3 # enlazar salida de echo a fichero pasado como parametro $3
- cd $1 # entrar al directorio especificado en $1
- raiz_pwd=$PWD # guardar la raiz de este directorio, la perderemos al recorrer el arbol en func_recursiva
- echo "chapter{Carpeta "$1"}" # crear la carpeta raiz como capitulo
- func_ficheros # procesar directorio raiz
- func_recursiva # llamar a func_recursiva para exploracion completa del directorio
Como veis, cada línea está bien comentada para que no haya ningún problema de comprensión.
La ejecución del script se realiza de la siguiente manera:
./myscript nombrecarpeta extensionfichero ficherolatex
Si por ejemplo queremos realizar un manual de código del conocido CMS Drupal, deberemos llamar al script de la siguiente forma:
neonigma@neonigma-laptop:/opt/lampp/htdocs$ ./myscript drupal php codigo.tex
En líneas generales, el script recorre la carpeta drupal de nuestro servidor Web buscando ficheros con extensión PHP y genera un fichero de LaTeX con la siguiente estructura:
chapter{Carpeta o subcarpeta}
section{Sección para fichero .php encontrado}
lstinputlisting{ruta al fichero php, que provocará el listado de código del mismo}
- El pdf resultante del proyecto LaTeX puede descargarse haciendo clic aquí.
- Podéis descargar el script pulsando aquí.
- El ejemplo de proyecto LaTeX, que incluye el fichero codigo.tex generado automáticamente por el script, puede descargarse pulsando aquí.
Saludos,
ante todo gracias por el script. No obstante me gustaría señalar que ya existen algunas herramietnas de generación automática de documentación de código fuente. Creo que el ejemplo más conocido es doxygen http://www.stack.nl/~dimitri/doxygen/ .
Correcto, Rafa. Doxygen documenta código y además separa funciones y demás.
Pero nunca subestimes el poder de aquello que amoldas a tu gusto. Y este script me hace la documentación a mi gusto, es decir, un listado simple de los ficheros de código. Sin más.
Por ejemplo, al utilizar Doxygen por vez primera en el ejemplo de documentación de Drupal, sólo ha tomado cuatro ficheros. Es evidente que quizás hago algo mal en la configuración, pero como siempre a veces merece la pena más personalizar tus requisitos (sobre todo si esto consume poco tiempo) que intentar encontrar la respuesta en otro software. Eso sí, no me cabe duda que Doxygen es un GRAN software.
Mi propuesta, además, en la misma línea de ejecución puedes modificar la extensión de ficheros a buscar, con lo que si no programas en PHP, puedes cambiar la extension a .java, y listo.
Estas son las razones por las que decidí compartir mi script.
Un abrazo.
muy bien, me gusto mucho tu creatividad y sin tantas complicaciones.
Muy bueno y sencillo.
Gracias!
¿como podemos poner más de una extensión? Gracias!!
Buenas Chema,
en principio, ejecutando el script varias veces y mezclando el codigo.tex a mano.