Advertising:
Crear un sitio web con Maven
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]
- http://maven.apache.org/doxia/ con los formatos apt, fml y xdoc y su conversión a html para el site.
- http://maven.apache.org/plugins/maven-site-plugin/index.html sobre el plugin para la generación del sitio.
- Foro de Maven y Ant