Crear el Site

En este artículo vamos a ver como funcionan algunos plugins. Especialmente el plugin site. Este plugin, nos permite generar una aplicación html con la descripción de nuestro proyecto.

La idea es escribir unos ficheros .pdm con las secciones fijas que queremos que se documenten (por ejemplo la descripción del proyecto, objetivos, métodos de acceso… etc.) y cada vez que ejecutemos las construcciones de nuestro proyecto a lo largo del ciclo de vida de la aplicación, se nos generará el despliegue de este “site” con la información de nuestro proyecto, junto con los “reports” (informes) de nuestro desarrollo, esto es, javadoc, resultado de la ejecución de los test, informes de calidad del código, bugs detectados, dependencias de nuestro proyecto… etc. Y todo esto, con una configuración mínima.

Lo bueno de esto, es que la configuración del site va en src/main/site/ y se versiona con el resto del proyecto, por lo que la documentación va asociada con la propia aplicación.

Usar el plugin de Pdm y el plugin Site

En las versiones antiguas de Maven, se incluía en el pom.xml un apartado “reporting” con la configuración de los informes, y era en ese apartado donde se añadía la configuración de pdm.

En la versión 3 de Maven, la configuración de los informes, va incluida en el plugin de generación del site.

Las fases del ciclo de vida “site” es la que nos compete en este capítulo:

  • pre-site → Ejecuta los procesos necesarios, previos a la generación del site
  • site →Genera el site con la documentación del proyecto
  • post-site →Ejecuta los procesos necesarios para finalizar la creación del site
  • site-deploy →Realiza un deploy del site de documentación, en el Web Server especificado
Generar el site

En maven 3 es necesario agregar el siguiente plugin a nuestra configuración ( ).

Una vez que tenemos nuestro proyecto Java podemos generar la documentación de dicho proyecto en formato Web, para poder publicarla. El comando mvn site, desde la carpeta del proyecto, nos generará el sitio Web por defecto. En el directorio target/site se genera el contenido del sitio Web para el proyecto.

Desplegar el Site

Se deben configuran los datos de acceso del servidor Web en el pom.xml:

Esta configuración sirve para subir usando el protocolo scp (Secure Copy) los contenidos de la carpeta target/site a nuestro servidor Web. Se pueden usar otros protocolos más comunes como FTP, por ejemplo:

En el fichero settings.xml se configuran los datos de la conexión dentro de .

Para desplegar el site:

Si tenemos configurado un jetty podemos ver como se ve el Site:

Descripción del Site

Habrá un menú en el lado izquierdo con un buen número de entradas en inglés que nos llevarán a diferentes páginas con información sobre el proyecto:

  • Una página “Acerca de…” con una breve descripción acerca del proyecto.
  • Una página “Integración continua” con info. sobre los sistemas de integración continua usados en el proyecto.
  • Una página “Dependencies” con un informe de las dependencias del proyecto: este es muy útil para averiguar que librerías usa nuestro proyecto y cual es el motivo de que aparezcan.
  • Lista de distribución de correo para el proyecto.
  • Información sobre gestión de plugins para proyectos que hereden información de este proyecto (pluginManagement).
  • Información sobre la licencia del proyecto.
  • Información de plugins usados en el proyecto.
  • Resumen organizativo del proyecto (coordenadas, nombre, página web).
  • Información sobre el equipo de trabajo del proyecto.
  • Información sobre el sistema de control de versiones utilizado en el proyecto (CVS, Subversion).

La mayoría de los informes no contienen información. Para poder disponer de dicha información es necesario especificarla en el pom.xml.

 Añadir informes al site

Los informes más habituales son:

  • javadoc → Los Javadocs de las clases del proyecto.
  • jxr →Una versión indexada del código fuente (como los javadocs pero muestran el código fuente).
  • surefire-report Un informe con el resultado de la ejecución de las clases de test.

Además de estos hay otros, todos ellos aparecen como enlaces en el menú izquierdo del sitio web, bajo el enlace “Project Reports”. Así es como se configuraría el informe javadocs:

Existen un buen número de plugins de informe, la mayor parte de ellos aparecen listados en http://maven.apache.org/plugins/ (Reporting plugins):

  • changelog: Informe con la lista de cambios generada a partir del histórico del sistema de control de versiones.
  • changes: Informe con una lista de cambios generada a partir de la información de un sistema de gestión de incidencias (ej: Bugzilla).
  • checkstyle: Informe sobre el estilo de escritura del código.
  • pmd: Análisis sobre posibles errores, malas prácticas y duplicación de código del proyecto.
  • cobertura: Informe con mediciones sobre el grado de cobertura de las clases de test.
Añadir contenido propio al site

Maven nos proporciona herramientas para añadir nuestras propias páginas al sitio web y enlazarlas desde el menú. Para configurar el sitio web,  escribimos un fichero site.xml en el directorio src/site del proyecto. En él indicaremos los detalles del sitio web:

  • bannerLeft: Para mostrar un icono o logo en el lado superior izquierdo de la página (con enlace opcional).
  • bannerRight: Para mostrar un icono o logo en el lado superior derecho de la página (con enlace opcional).
  • links: Debajo de los logos anteriores aparecerá una barra horizontal. En el lado derecho de esta barra aparecerán los enlaces que pongamos dentro de esta etiqueta links.
  • menu: Podemos poner varias etiquetas menú y dentro de ellas los items que queramos. El tag name será el texto que aparezca en cada entrada del menú y los tag href las páginas a las que enlazan estos item de menú.

Para escribir/editar las páginas a las que apuntan estos item de menú se usa alguna de los lenguajes de escritura definidos por Maven, el más usual es el lenguaje APT (Almost Plain Text) que es un formato muy sencillo parecido al lenguaje usado en las wikis para escribir contenido con formato. En el directorio src/main/site/apt guardamos los archivos, en este formato, con el texto que queremos que aparezca en cada una de las páginas a las que apuntan los item. En el caso del fichero anterior serían necesarios los siguientes ficheros:

  • src/main/site/apt/indice.apt
  • src/main/site/apt/maven3.apt
  • src/main/site/apt/hibernate.apt

Hay que darse cuenta que los ficheros originales tienen extensión .apt , mientras que en los enlaces los referenciamos como .html , esto es debido a que Maven al generar el sitio web genera una copia en formato html (src/main/site/apt/indice.apt > target/site/indice.html ). En los ficheros .apt sólo debemos ocuparnos del contenido de nuestra página, y no de los adornos alrededor de ella. Si queremos que en nuestra documentación haya imágenes o cualquier otro tipo de fichero, debemos meterlo en src/site/resources. Vamos a ver un ejemplo. Creamos en src/main/site/apt/ el archivo maven3.apt Añadiremos el contenido de este fichero en formato apt: Referencia formato apt

El resultado de lo anterior es el siguiente:

Ejemplo del site y de una página apt

Ejemplo del site y de una página apt

Hemos señalado con flechas los elementos configurados en el site.xml. En la derecha se muestra un montaje de algunos elementos que se pueden conseguir con los archivos .apt

Configuración de informes (reports) en Maven 3

En Maven 3 se configura de este modo:

En el  apartado donde pone foo… esos son los goals del plugin, los valores que pueden tomar son:

index, scm plugin-management, mailing-list, issue-tracking, help, plugins, dependency-convergence, summary, dependency-management, dependencies, license, modules, project-team, cim. Para incluir el javadoc, hay que añadir el siguiente plugin en el código anterior, en el lugar marcado con :

Se creará una entrada de menú que enlazará con el javadoc de nuestros .java:

Detalle de la entrada JavaDocs

Detalle de la entrada JavaDocs

Incluir el plugin pdm

Este plugin no funciona si, como ocurre con Windows, la ruta al repositorio local de maven contiene espacios. Por ejemplo, si el plugin estña en: “C:\Documents and Settings\usuario\.m2\repository\pmd\pmd\4.3” no va a poder encontrar ciertos archivos xml, que se encuentran en dicho plugin.

Para mover el repositorio local de maven a una carpeta sin espacios, localizamos el archivo settings.xml de nuestra instalación maven y editamos la ruta al repositorio:

Configuramos el plugin pdm para que emita informes en nuestro proyecto. Hemos creado una      clase de test, con errores, para ver como se comporta el plugin. Como en el caso anterior, añadimos la siguiente configuración en el pomm en el lugar marcado con “”:

Si ejecutamos mvn site vemos los resultados:

Estili de codificación

Estili de codificación

Infrome CPD

Informe cpd

Informe cpd

Incluir el plugin changelog

Este plugin devuelve el listado de cambios que se han llevado a cabo en el sistema de control de versiones (scm). Para añadirlo, como en el resto de los casos, se pondría lo siguiente en el lugar que hemos marcado con “”:

Incluir el plugin checkstyle y jxr

Como hemos hecho anteriormente, vamos a instalar estos dos plugins en el apartado del plugin site. maven-jxr-plugin → Este plugin muestra el código fuente de nuestras clases.

Código fuente de las clases

Código fuente de las clases

maven-checkstyle-plugin → Este plugin muestra los errores de estilo que hay en el código. Si se ha instalado el plugin anterior, también enlaza con la línea de código que tiene el error:

Errores de estilo

Errores de estilo

Vamos a indicar una configuración básica de estos plugins:

Incluir el plugin StatSCM

StatSCM es un plugin que genera gráficos impresionantes y datos sobre un proyecto en un sistema de control de versiones (CVS y Subversion). Vamos a ver como se configura:

No necesitamos hacer nada más. Este plugin nos creará diferentes gráficas con la información relacionada con el control de versiones, el resultado es espectacular:

Resultado del plugin StatSCM

Resultado del plugin StatSCM

Incluir el plugin Cobertura e informes de test JUnit

El plugin de cobertura, nos indica el porcentaje de líneas ejecutadas por los test, el porcentaje de ramas, etc.

Resultado de los test de cobertura

Resultado de los test de cobertura

Respecto al plugin “surefire”, nos genera un informe con los resultados de los test:

Resultado de los test

Resultado de los test

Como se puede ver, nos indica que hay un fallo en el test de la clase Suma. Pinchando nos lleva al ancla que muestra el detalle de los errores. Y si pinchamos en el enlace, nos llevaría a la linea del test que falló:

Detalle de los fallos

Detalle de los fallos

 
El plugin Pdf

Se puede generar un pdf, con la información del site que hemos creado en src/site/ ejecutando:

Si queremos ejecutar la generación del pdf, como parte de la generación del site:

En la carpeta src/site/pdf.xml, podemos definir el índice, o incluir cierta información. Para conocer los detalles se recomienda consultar la documentación

 

Deja un comentario

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