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ónUna 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:
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ásicosAntes 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
<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:
El formato para Connection comprende de 3 partes separadas por ":":
<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 ContinuaAquí 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 DistribucionEn 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>
<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>
Configuraciones para el sitio de documentaciónLas 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> <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 UMLEste 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 CoberturaEstos 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> 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 JUnitReporte 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>
|
Página principal >