Crea un manual de código en LaTeX de forma automática

Posted on por

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:

< View plain text >
bash

  1. #!/bin/bash
  2. #set -e
  3. #set -u
  4.  
  5. #set -x
  6.  
  7. func_ficheros()
  8. {
  9.     listaficheros=$(find -maxdepth 1 -type f -iname "*."$extpar | sort) # extraer lista ordenada de ficheros del directorio actual
  10.  
  11.     for item in $listaficheros # recorrer lista de ficheros
  12.     do
  13.         extfich=${item##*.} # obtener extension del fichero
  14.         if [ $extfich = $extpar ] # si la extension es la misma que especificamos en $2
  15.         then
  16.             fichero=${item##*"./"} # eliminar todos los "./" que coloca find
  17.             fichero=${fichero//"_"/"_"} # reemplazar todos los "_" por "_", LaTeX trata "_" como error
  18.             echo "section{Fichero "$fichero"}" # creamos la seccion con el nombre del fichero
  19.             echo -e "lstinputlisting{"$PWD"/"${item##*"./"}"}n" # incluimos el fichero con ruta completa y con "_" porque es ruta fisica
  20.         fi
  21.     done
  22. }
  23.  
  24.  
  25. func_recursiva()
  26. {
  27.     for OBJ in * # recorrer el directorio $1
  28.     do
  29.         (
  30.         if [ -d "${OBJ}" ] # es un directorio
  31.         then
  32.             cd "${OBJ}" # cambiar a este directorio
  33.             var=$(find -maxdepth 1 -type f -iname "*."$extpar | wc -l) # ver si hay en el directorio actual ficheros de tipo $2
  34.            
  35.             if [ $var != "0" ] # si hay ficheros de tipo $2
  36.             then
  37.                 nombrecarpeta=${PWD##*$raiz_pwd} #extraer solo el nombre de la carpeta
  38.                 carpeta=${nombrecarpeta//"_"/"_"} # reemplazar todos los "_" por "_", LaTeX trata "_" como error
  39.                 echo -e "n" # retorno de carro
  40.                 echo "chapter{Carpeta "$dirpar$carpeta"}" # crear nueva subseccion con esta subcarpeta
  41.  
  42.                 func_ficheros # procesar los ficheros de este directorio
  43.             fi
  44.             func_recursiva # seguir mirando subcarpetas
  45.         fi
  46.         )
  47.     done
  48. }
  49.  
  50. #################
  51. #          INICIO            #
  52. #################
  53.  
  54. if [ $# != 3 ] # control de errores - utilizar los tres parametros: nombrecarpeta, extensionfichero y ficherolatex
  55. then
  56.     echo -e "ERROR: Incorrecto numero de argumentosn"
  57.     echo "Uso del programa: ./myscript nombrecarpeta extensionfichero ficherolatex"
  58.     echo "Ejemplo: ./myscript micarpeta php codigo.tex"
  59.     exit 0
  60. fi
  61.  
  62. dirpar=$1 # obtener el parametro de carpeta raiz, en func_recursiva se pierde la visibilidad del parametro
  63. extpar=$2 # obtener el parametro de extension a buscar, en func_recursiva se pierde la visibilidad del parametro
  64.  
  65. exec 1&gt;$3 # enlazar salida de echo a fichero pasado como parametro $3
  66.  
  67. cd $1 # entrar al directorio especificado en $1
  68. raiz_pwd=$PWD # guardar la raiz de este directorio, la perderemos al recorrer el arbol en func_recursiva
  69. echo "chapter{Carpeta "$1"}" # crear la carpeta raiz como capitulo
  70.  
  71. func_ficheros # procesar directorio raiz
  72. 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í.
A 5 personas les gusta esta entrada

6 pensamientos en “Crea un manual de código en LaTeX de forma automática”

  2. 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.

Deja una respuesta

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