Una buena práctica a la hora de publicar nuestros proyectos es, sin duda, crear un site para el proyecto en el que podamos añadir toda la información sobre el proyecto, desarrolladores, código fuente (en caso de desear compartirlo), informes sobre test,
"issue tracking" y un sin fin de cosas. Es lógico que crear un site con toda está información desde cero es muy costoso, por tanto voy a proponer un sistema automático.
Para llevar a cabo esta automatización podemos usar el plugin de maven
"Maven Site Plugin", el cuál generará el site automáticamente con toda la información que definamos en su configuración. Lo primero que debemos hacer es añadir el plugin en nuestro fichero pom.xml:
<project>
...
<build>
<!--Para usar las metas del plugin-->
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>2.0.1</version>
</plugin>
...
</plugins>
</build>
...
</project>
Si queremos definir el plugin en el pom padre para que sea usado por todos los proyectos hijos podemos usar esto:
<project>
...
<build>
<!-- Para definir el plugin en el POM Padre-->
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>2.0.1</version>
</plugin>
...
</plugins>
</pluginManagement>
...
</build>
...
</project>
Una vez que tenemos esto podemos ejecutar el comando
mvn site para crear nuestro site, por defecto lo creara en la carpeta
{basedir/target/site}. Obviamente el site generado tendrá la configuración por defecto y creará el contenido por defecto, estando la mayoría de la información sin rellenar. Algunos apartados puedes tener datos, como las dependencias o la información del proyecto y los desarrolladores, que serán extraídas del pom.
Configurar el site.Para configurar el site a nuestro gusto e ir añadiendo la información que deseemos. En la carpeta src debemos crear la siguiente estructura:
+- src/
+- site/
+- apt/
| +- index.apt (versión por defecto)
|
+- site.xml (descriptor de la versión por defecto)
Para cambiar el ábol de navegación debemos configurar nuestro descriptor del site (site.xml), podemos ver como se crea un descriptor del fichero en la
página oficial del plugin.
Configurar los informesPodemos añadir los informes que generamos con otros plugins de maven. Hay muchos informes estándar disponibles que obtienen información del POM. Actualmente los que se proveen por defecto son los siguientes:
- Informe de dependencias
- Listas de correo
- Integración Continua
- Repositorio de código fuente
- Seguimiento de errores (Issue Tracking)
- Equipo del proyecto
- Licencia.
Para añadirlos tan sólo debemos configuralos en la sección
del POM y añadir las entradas correspondientes en el fichero site.xml, si esté ha sido modificado, ya que en el fichero por defecto se incluyen dichas secciones.
<project>
...
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.0.1</version>
</plugin>
</plugins>
</reporting>
...
</project>
Internacionalización.La internacionalización de nuestro site es muy sencilla, tan sólo debemos configurar el plugin para que admita varios locales, añadiendo en la configuración del plugin:
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>2.0.1</version>
<configuration>
<locales>en,es</locales>
</configuration>
</plugin>
</plugins>
</build>
...
</project>
Y luego crear una carpeta para el contenido para cada idioma, el contenido del idioma por defecto irá en la carpeta raíz y crearemos una carpeta para cada idioma extra. Asimismo crearemos un descriptor del site en cada idioma, sería algo así:
+- src/
+- site/
+- apt/
| +- index.apt (versión por defecto)
|
+- es/
| +- apt/
| +- index.apt (versión en español)
|
+- site.xml (descriptor de la versión por defecto)
+- site_es.xml (descriptor de la versión española)
Ejecución y despliegue del Site.
Una vez que tenemos nuestro site, podemos ejecutarlo usando nuestra máquina como servidor con el comando
mvn site:run y
podemos acceder a él en el puerto 8080 del localhost (http://localhost:8080/). Si disponemos de un dominio y almacenamiento para nuestro site podemos publicarlo automáticamente, para ello debemos añadir en nuestro POM la la información de la URL a la que subiremos el site, en la configuración del
distributionManagement:
<project>
...
<distributionManagement>
<site>
<id>www.yourcompany.com</id>
<url>scp://www.yourcompany.com/www/docs/project/</url>
</site>
</distributionManagement>
...
</project>
y luego ejecutar el deploy, para ello tenemos dos opciones:
- mvn site:deploy : Este comando sólo despliega el site, por tanto el sitio debe haberse generado antes.
- mvn site-deploy : Si queremos ejecutar todo el proceso desde generarlo hasta su publicación debemos ejecutar la fase site-deploy del ciclo de vida.
Os dejo un proyecto de prueba vacío en el que se aplica todo esto, para generar un site.
Como vemos, con esta herramienta podemos ahorrar mucho tiempo y generar un site con toda la información del proyecto, en otra ocasión continuaremos con más buenas prácticas.
Saludos.
