Configuración Maven POM para reportes en el Sitio de Documentación

Tema: Mostrar las configuraciones básicas y específicas que se requieren en Maven para mostrar un sitio de documentación completo.

Categoria: Tip / Programación

Tecnologías / Componentes: Maven

Introducción

Una de las ventajas de Maven es poder crear un sitio de documentación ("site" en inglés) lo más fácil y rápido posible.

Esto se realiza en la fase "site" y se puede ejecutar con el comando:

mvn site:site

Además, dentro del archivo de configuración (pom.xml) podemos personalizar este sitio.

El sitio original contiene información básica del proyecto, el cual obtiene de los datos básicos de configuración del POM y de dependencias, etc.

En este artículo pondré las configuraciones necesarias para agregar una sección extra de Reportes, tales como:

Documentación javadoc
Resultados de Cobertura
Resultados de análisis estático de código
y demás herramientas que son útiles.

Por lo que el sitio de documentación se verá de la siguiente manera:

Todas estas configuraciones son dentro del POM

Configuración de datos básicos

Antes de personalizar el "sitio", debemos asegurarnos que los datos básicos del POM han sido llenados correctamente. Estos datos son necesarios por 2 razones: Principalmente porque proveen información importante en el sitio, información que puede ser usada en varias secciones y/o sistemas con sólo haber llenado estos campos; además que también sirven para ciertas actividades en específico.

Por ejemplo, la sección <distributionManagement> provee información en la documentación en el sitio y además se requiere para poner los artefactos finales (war, jar, pom, etc) en el repositorio institucional como Nexus.

Por lo tanto las configuraciones básicas y necesarias son:

Datos básicos del proyecto:

Además del groupId, parent, etc, es necesario que mencionemos la

descripción: Info básica de qué hace el proyecto
y la url del proyecto: La liga del sitio del proyecto: También puede apuntar a la url donde se expondrá esta documentación del site en internet o en la intranet de la empresa.

<description>Descripción de qué hace el proyecto.</description>

<url>http://URL_SITE/MI_PROYECTO</url>

Datos Institucionales

<organization>
<name>MI EMPRESA</name>
<url>http://URL_EMPRESA</url>
</organization>

Datos del Controlador de Código / Versiones (SCM)

Aquí especificamos la ruta donde se guarda el código fuente en el repositorio SCM. Se comprende de 3 secciones:

Connection: Esta liga se usa al hacer el release, ya que el plugin Maven-Release hace checkout de esta liga para después realizar el TAG liberado
DeveloperConnection: Esta es la liga que en la documentación especifica al desarrollador de donde puede bajar el código. Por lo regular es la misma que Connection.
Url: Es la liga del repositorio en general, donde se encuentra el código. Por lo regular, apunta a la raiz del proyecto y NO a un tag, branch o trunk en específico.

El formato para Connection comprende de 3 partes separadas por ":":

"scm": es una constante.
Tipo de repositorio: Puede ser "svn" para subversion, "cvs" o "git"
Url: Puede ser al trunk o alguna rama

<scm>
<connection>scm:svn:http://MI_SERVER/svn/MI_PROYECTO/trunk/</connection>
<developerConnection>http://MI_SERVER/svn/MI_PROYECTO/trunk/</developerConnection>
<url>http://MI_SERVER/svn/MI_PROYECTO</url>
</scm>

Datos de Integración Continua

Aquí especificamos los datos del servidor de integración continua y cuál usamos (Jenkins, Bamboo, etc..)

<ciManagement>
<url>http://MI_SERVER/jenkins/</url>
<system>jenkins</system>
</ciManagement>

Datos de Sistema de Distribucion

En esta sección se especifíca los datos del repositorio de artefactos institucionales como Nexus o Artefactory

Además, se especifica dónde se publicará el sitio. Esta información la requiere en Plugin que publica o copia a un servidor remoto, el cual se especifica más adelante.

<distributionManagement>


<site>

<id>site.deployments</id>
<name>Titulo de Documentacion</name>
<url>Liga a la documentacion (http) o a donde se copiara (scp,etc)</url>
</site>

<downloadUrl> http://URL_PARA_OBTENER_CODIGO_O_ARTEFACTO/</downloadUrl>

<repository>
<id>nexus</id>
<name>Nexus Releases</name>
<url>http://MI_REPO/nexus/content/repositories/MI_REPO_RELEASES/</url>

</repository>

<snapshotRepository>
<id>nexus</id>
<name>Nexus Snapshots</name>
<url>http://MI_REPO/nexus/content/repositories/MI_REPO_SNAPSHOTS/</url>
</snapshotRepository>


</distributionManagement>

Configuraciones para el sitio de documentación

Las siguientes configuraciones son para agregar más categorías a la sección de Reportes en la documentación para que se vea de la siguiente manera:

Por lo tanto, las siguientes configuraciones deberán ir dentro de la sección <reporting>, como se muestra a continuación:

<reporting>
<plugins>

...
</plugins>

</reporting>

En Maven 3.x se especifican en la sección <build> y dentro de cada plugin, sin embargo, en lo particular me gusta más tener todas las configuraciones concentradas dentro de una misma sección; así que apesar que esta configuración es de la especificación de Maven 2.x aún sigue siendo compatible con Maven 3.x

La mayoría de estos reportes son de pruebas y análisis estáticos de código; para mayor información sobre tipo de pruebas se pueden ver el post: Tipo de Pruebas para Desarrollo de Software

JavaDoc con gŕaficos UML

Este reporte obtendrá los comentarios del código y realizará la documentación de JavaDocs, además utilizaremos un plugin de UmlGraphDoc el cual incluirá en cada clase un diagrama UML en caso que conviva con otras clases o interfaces.

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.8</version>
<configuration>
<doclet>org.umlgraph.doclet.UmlGraphDoc</doclet>
<docletArtifact>
<groupId>org.umlgraph</groupId>
<artifactId>doclet</artifactId>
<version>5.1</version>
</docletArtifact>
<additionalparam>-views</additionalparam>
<useStandardDocletOptions>true</useStandardDocletOptions>
</configuration>
</plugin>

Reportes de Cobertura

Estos reportes son los de cobertura de las pruebas unitarias

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>cobertura-maven-plugin</artifactId>
<version>2.5.1</version>
<configuration>
<formats>
<format>html</format>
<format>xml</format>
</formats>
</configuration>
</plugin>

Reporte de TODOs Pendientes

Este reporte enlista los Tags @TODO que se encuentran en el código. Por lo que se tienen que tener presentes, ya que un sistema con muchos tags @TODOS implica que aun tiene pendiente de implementación de código.

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>taglist-maven-plugin</artifactId>
<version>2.4</version>
</plugin>

Reporte de Historial de Cambios en el SCM (Repositorio)

Este reporte enlista los cambios que se han realizado en el repositorio de versiones al momento de hacer "commits".

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-changelog-plugin</artifactId>
<version>2.2</version>
</plugin>

Reportes de Pruebas Unitarias con JUnit

Reporte que especifica el status de las pruebas unitarias

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-report-plugin</artifactId>
<version>2.9</version>
</plugin>

Referencias de Pruebas Unitarias al Código

Reporte de pruebas unitarias, pero se puede ir haciendo clicks y hace referencia al código

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jxr-plugin</artifactId>
<version>2.3</version>
</plugin>

Reporte de FindBugs

Reporte de Checkstyle

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>2.9.1</version>
<configuration>
<configLocation>config/sun_checks.xml</configLocation>
</configuration>
</plugin>

Reporte de PMD

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>2.5</version>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>javancss-maven-plugin</artifactId>
<version>2.0-beta-2</version>
</plugin>

Liga a Análisis en Sonar

En caso que el proyecto haya pasado por análisis en Sonar, esta sección será una liga autoredirigida al proyecto en Sonar.

<plugin>
<groupId>org.codehaus.sonar-plugins</groupId>
<artifactId>maven-report</artifactId>
<version>0.1</version>
</plugin>

Pruebas de Aceptación de Usuario con Thucydides

Este reporte redirige al reporte que Thucydides arrojó al hacer las pruebas de aceptación de usuario

<plugin>

<groupId>net.thucydides.maven.plugins</groupId>

<artifactId>maven-thucydides-plugin</artifactId>

<version>${thucydides.version}</version>

</plugin>

Configuración para publicar el sitio en un servidor remoto

Existe un plugin (org.apache.maven.wagon) que nos puede ayudar a publicar nuestro sitio de documentación en un servidor remoto. Esto lo puede hacer mediante ftp, scp o webdav.

Una vez que ya está configurado se puede ejecutar con los comandos:

mvn site:site site:deploy

Nota

site:deploy requiere que el sitio ya esté generado (con site:site).

Sin embargo, se puede hacer en un solo paso con el comando

mvn site-deploy

A continuación un ejemplo con scp.

Configuración del plugin

Esta configuración va en la sección <build>.

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.1</version>
<dependencies>

<dependency>
<groupId>org.apache.maven.wagon</groupId>
<artifactId>wagon-ssh</artifactId>
<version>1.0</version>
</dependency>
</dependencies>
</plugin>

...

</plugins>
</build>

Configuración de credenciales del servidor

Hay que agregar la configuración de credenciales al servidor en el archivo settings.xml de Maven, en la sección <servers>.

<server>
<id>site.deployments</id>
<username>MI_USERNAME</username>
<password>MI_CONTRASEÑA</password>
<privateKey>/path/to/private/key</privateKey>
</server>

Credenciales

En caso que se use una llave privada para ingresar y NO la contraseña, DEBERÁ omitirse el tag <password>, en caso contrario, no tomará la llave privada.

Resumen

Es importante tener una documentación del proyecto, y mejor aún si está en un sitio concentrado.

El poder realizar un sitio de una manera fácil, sencilla y automatizada es parte de la filosofía de Integración Continua y en específico como Continuous Documentation. La ventaja que podemos utilizar es poniendo esta actividad como un "JOB" más en el "Pipeline" de nuestro servidor de Integración Continua..

Nota

Hay que tener en mente que al momento de hacer el release de nuestro proyecto, esta fase de generación del sitio "site:site" viene ímplicito, por lo que si el pipeline contiene una actividad de release, este JOB lo podemos ahorrar, ya que se ejecutará en automático

Post Similares

Titulo	Descripción	Categoria	Tecnologías	Tipo	Fecha de publicación
Subversión y Jenkins: cómo comunicarse entre ellos	Como poder indicarle a Jenkins iniciar una actividad cuando Subversion ha sido actualizado	Integración continua	Subversion, Jenkins	Tip	17 de septiembre de 2012
Jenkins & Sonar: Status en jenkins refleje alertas de sonar	Cómo poder mostrar en Jenkins el status real dependiendo de las alertas de Sonar	Integración continua	Subversion, Jenkins	Tip	29 de agosto de 2012
Web Tiers: Explicación	Explicación sobre el concepto "tiers" en proyectos web.	Diseño	Servlets	Explicación	1 de septiembre de 2009
Tipo de Pruebas para Desarrollo de Software	Explicación sobre los diferentes tipos de pruebas que se pueden hacer en el desarrollo de software	Calidad	XUnit, Sonar, PMD, Findbugs, Thucydides, Checkstyle, Cobertura	Explicación	11 de septiembre de 2012
Integración Continua: Promociones y Líneas de Producción	Explicación del concepto de promociones y pipelines en Integración Continua	Integración continua	Jenkins y plugins	Explicación	27 de septiembre de 2012

Mostrando 5 elementos de la página Indice de posts ordenados por hora de edición. Ver más »

Comments

Java & Arch Blog	Buscar en este sitio