Crear un sitio web con Maven

From ChuWiki
Jump to navigation Jump to search

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[edit]

Retrieved from "https://chuidiang.org/index.php?title=Crear_un_sitio_web_con_Maven&oldid=3453"