Crear un sitio web con Maven

De ChuWiki
Saltar a: navegación, buscar

Una vez que tenemos nuestro proyecto Maven, podemos generar la documentación de dicho proyecto en formato web, para poder publicarla. En http://proyectos.chuidiang.com/graficos/ tienes un ejemplo de sitio web generado con maven.

Si no hacemos nada especial, el comando mvn site nos generará el sitio web por defecto, con la documentación e informes por defecto. El comando

$ mvn site

generará en el directorio target/site el sitio web para nuestro proyecto. Habrá un menú en el lado derecho con un montón de opciones en inglés que al pulsarlas nos llevarán a una página en inglés que básicamente dice que no hay información asociada a ese enlace.

Sin embargo, nosotros podemos configurar cómo queremos el sitio web y el contenido del mismo. Veamos un pequeño ejemplo de cómo hacerlo.

Primero, en src/site escribimos un fichero site.xml en el que indicaremos qué cosas queremos. El contenido de este fichero puede ser similar a este

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Libreria Grafica en Java">

   <bannerLeft>
      <name>Chuidiang</name>
      <src>serpi.gif</src>
      <href>http://www.chuidiang.com/</href>
   </bannerLeft>

   <bannerRight>
      <src>
         http://i.creativecommons.org/l/by-nc-sa/2.5/es/88x31.png
      </src>
      <href>
         http://creativecommons.org/licenses/by-nc-sa/2.5/es/deed.es
      </href>
   </bannerRight>

   <body>
      <links>
         <item name="Libreria Grafica en Java"
            href="http://proyectos.chuidiang.com/graficos/index.html" />
         <item name="Foro" href="http://foro.chuidiang.com/" />
         <item name="Blog" href="http://blog.chuidiang.com/" />
      </links>

      <menu name="Librería Gráfica">
         <item name="Introducción" href="indice.html" />
         <item name="Descarga" href="download.html" />
         <item name="Ejemplos" href="ejemplos.html" />
      </menu>

      <menu name="Informacion">
         <item name="Licencia" href="licencia.html" />
         <item name="Desarrolladores" href="desarrolladores.html" />
      </menu>

      <menu name="Informes">
         <item name="Cobertura" href="cobertura/index.html" />
         <item name="Javadoc" href="apidocs/index.html" />
         <item name="Fuentes" href="xref/index.html" />
      </menu>
   </body>
</project>

Este fichero es el que he usado para obtener la documentación de http://proyectos.chuidiang.com/graficos/

En el fichero site.xml vemos los siguientes tags:

  • bannerLeft, para mostrar un icono en el lado superior izquierdo de la página.
  • bannerRight, para mostrar un icono en el lado superior derecho de la página.
  • links. Debajo de los dos iconos 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 menu y dentro de ellas los item que queramos. Estos menus aparecerán en una barra vertical en el lado izquierdo. El name del menu será el título del menú y los items serán los que se indiquen.

Para generar las páginas html a las que apuntan estos item de menú, tenemos una forma sencilla. En el directorio src/main/site/apt escribimos, en formato apt, 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, tendría creados los siguientes ficheros

  • src/main/site/apt/indice.apt
  • src/main/site/apt/download.apt
  • src/main/site/apt/ejemplos.apt
  • src/main/site/apt/licencia.apt
  • src/main/site/apt/desarrolladores.apt

El formato apt -Almost Plain Text o Texto Casi Plano- es un formato similar al de las wikis, aunque no igual. Puedes ver algo sobre este formato en http://maven.apache.org/doxia/references/apt-format.html

Al ejecutar el comando mvn site, maven cogerá estos ficheros y los convertirá en ficheros .html, pero añadiendo los banner superiores, barra de menú horizontal y barra vertical en el lado izquierdo. Por ello, 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 imagenes o cualquier otro tipo de fichero, debemos meterlo en src/main/site/resources. Lo que pongamos ahí estará luego disponible en el path relativo resources/imagen.gif.

En cuanto a los informes por defecto de maven, si en nuestro fichero site.xml ponemos algo como

<menu ref="modules" />

eso creará un menu con todos los informes e informacion del proyecto por defecto. En mi caso, como me parece excesivo, simplemente he optado por no ponerlo y añadir mi propio menú con tres items, apuntando a los tres informes que me interesan: cobertura, javadoc y fuentes. Los href de dichos item los he puesto viendo dónde se generan dichos informes y apuntando a esa ubicación.

Por supuesto, todo esto es mucho más configurable. Existen formatos además de apt más adecuados para contar los cambios de una revisión -xdoc- a otra y para las preguntas frecuentes -fml-


Enlaces