En mi anterior post comentaba que íbamos a comenzar a utilizar Doxygen para generar la documentación de nuestros fuentes. Pues bien, en esta entrada voy a comentar como ha resultado la integración de Doxygen dentro del ciclo de vida de mis proyectos.
Para integrar Doxygen con Maven he usado doxygen-maven-plugin. Este plugin básicamente lo que hace es invocar a la herramienta doxygen en la fase de generación de reportes y proporcionarle los parámetros de configuración propios de la herramienta. También existe la posibilidad de invocarlo de forma explícita.
Lo primero que necesitamos es instalar Doxygen en el equipo donde se va a construir el proyecto. En mi caso es un servidor que forma parte de nuestro ecosistema software destinado única y exclusivamente a llevar a cabo tareas de integración continua. Que no se os olvide instalar la herramienta GraphViz porque la necesitaremos para generar los gráficos de entidades y relaciones.
Una vez que tenemos estas herramientas instaladas necesitamos modificar nuestro archivo P.O.M. añadiendo el repositorio de plugins de donde se descargará el plugin que necesitamos:
<pluginRepository>
<id>doodleproject-repo</id>
<name>DoodleProject Maven 2 Repository</name>
<url>http://doodleproject.sourceforge.net/maven2/release</url>
<releases>
<enabled>true</enabled>
</releases>
</pluginRepository>
Una vez que hemos añadido el repositorio de plugins pasamos a configurar el plugin:
<plugin>
<groupId>net.sf.doodleproject</groupId>
<artifactId>doxygen-maven-plugin</artifactId>
<configuration>
<executable>${doxygenExecutable}</executable>
<configurationFile>../opina-doxygen.conf</configurationFile>
</configuration>
</plugin>
En la documentación del plugin se añade un nodo adicional justo debajo de “configuration”, sin embargo, observando el código fuente del plugin, comprobé que no era necesitario (quizás un bug). En esta configuración simplemente se le indica la ubicación del ejecutable y el archivo de configuración. Como uno de los objetivo de Maven es evitar la dependencia con los entornos de desarrollo locales, no tiene sentido haber puesto el path correspondiente a mi instalación local de Doxygen, por eso definí una variable que añadí a mi correspondiente perfil (profile.xml).
El archivo de configuración de Doxygen lo creé con el asistente gráfico que proporciona, y posteriormente lo retoqué. Algunas notas sobre el archivo de configuración:
- OUTPUT_DIRECTORY: Indicar un path relativo y correspondiente con la estructura de directorios propuesta por Maven, p.e. target/site/doxygen
- INPUT: Idem, p.e. src/main/java
- Evidentemente, lo deseable sería que estos parámetros correspondieran con ${project.reporting.outputDirectory}/doxygen y ${project.build.sourceDirectory} respectivamente. Sin embargo, para conseguir esto deberíamos aplicarle un filtro y colocarlo como un recurso.
Un inconveniente que posee este plugin es que no se integra bien con la generación del sitio web de Maven. No se genera correctamente el enlace a la documentación. En Opina para evitar este problema, hemos añadido un enlace en la menú de la izquierda. Lo tenéis publicado por si alguien quiere verlo.
Recent Comments