Crear un sitio web con Maven

De ChuWiki


maven-site-plugin[editar]

Una vez que tenemos nuestro proyecto Maven, podemos generar la documentación de dicho proyecto en formato web, para poder publicarla. El encargado de hacerlo es maven-site-plugin, que viene por defecto con Maven.

Site por defecto[editar]

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. La siguiente imagen muestra el sitio web creado para un proyecto Maven recién creado.

Sitio web por defecto creado por maven-site-plugin
Sitio web por defecto creado por maven-site-plugin

Hay 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 dirá información que puede sacar directamente del proyecto, como dependencias, plugins usados o textos por defecto indicando que no hay descripción.

Configuración del site generado[editar]

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="UTF-8"?>
<project name="Libreria Grafica en Java">

    <bannerLeft>
        <name>Chuwiki</name>
        <src>images/serpi.gif</src>
        <href>https://chuidiang.org/</href>
    </bannerLeft>

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

    <body>
        <links>
            <item name="Chuwiki"
                  href="https://chuidiang.org" />
            <item name="Foro" href="https://foro.chuidiang.org/" />
            <item name="Blog" href="https://blog.chuidiang.org/" />
        </links>

        <menu name="Ejemplo de maven-site-plugin">
            <item name="Introducciónn" href="indice.html" />
            <item name="Descarga" href="download.html" />
            <item name="Ejemplos" href="ejemplos.html" />
        </menu>

        <menu name="Información">
            <item name="Licencia" href="licencia.html" />
            <item name="Desarrolladores" href="desarrolladores.html" />
        </menu>

        <menu name="Informes">
            <item name="Tests" href="surefire-report.html" />
            <item name="Cobertura" href="jacoco/index.html" />
            <item name="Javadoc" href="apidocs/index.html" />
            <item name="Fuentes" href="xref/index.html" />
            <item name="Métricas" href="pmd.html" />
        </menu>
    </body>
</project>
</project>

En el fichero site.xml vemos los siguientes tags:

Logos del site[editar]

Tenemos dos posiciones para poner logos. Arriba a la izquierda y arriba a la derecha.

  • <bannerLeft>, para mostrar un icono en el lado superior izquierdo de la página. La imagen puede ser una URL a un sitio exterior, o bien una imagen que coloquemos dentro de src/site/resources. En mi caso, puse src/site/resources/images/serpi.gif que luego, en el site estará accesible en images/serpi.gif.
  • <bannerRight>, para mostrar un icono en el lado superior derecho de la página. Idem al anterior.

Pudes verlo en src/site/resources

Enlaces[editar]

Debajo de los logos anteriores aparecerá una barra horizontal. En el lado derecho de esta barra aparecerán los enlaces que pongamos dentro de la etiqueta <links>.

Menú[editar]

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 item serán los que se indiquen.

En estos item podemos enlazar a páginas que creemos especificamente para el proyecto o bien a informes generados por algunos de los plugin de maven como el de test (maven-surefire-report-plugin), la cobertura de los test (jacoco-maven-plugin), javadoc (maven-javadoc-plugin), fuentes (maven-jxr-plugin) o métricas (maven-pmd-plugin).

Páginas propias del site[editar]

Para escribir las páginas html a las que apuntan estos item de menú, tenemos varias formas. Maven site plugin entiende varios formatos para el texto y los traducirá a html, por lo que no tenemos necesariamente que escribir en html. Los fomatos que soporta

  • APT: "Almost Plain Text" es un formato similar al de una wiki. Podemos escribir las páginas dentro src/site/apt con extensión .apt.
  • FML: "FAQ Markup Language" es un formato XML típico para las FAQ (Frecuent Asked Questions). Podemos escribir las páginas dentro de src/site/fml.
  • XDoc: Es un formato de texto en XML, similar a html, pero no igual. Podemos escribir las páginas dentro src/site/xdoc con extensión .xdoc.
  • 'Markdown: Otro formato similar al de una wiki, más conocido que apt. Podemos escribir las páginas dentro src/site/markdown con extensión .md.
  • xhtml: Es el formato html extendido. Podemos escribir las páginas dentro src/site/xhtml con extensión .xdoc.

Por supuesto, podemos mezclar y escirbir unos documentos en un formato y otros en otro, siempre colocándolos en los directorios adecuados y procurando que no coincidan nombres.

maven-site-plugin cogerán estos ficheros, los traducirán a html, poniendo alrededor toda la "decoración" propia del sitio maven que estamos construyendo. Así que no nos tenemos que ocupar de poner los logos, menú y demás. Basta con escribir el texto específico de esa página.

Para nuestro ejemplo hemos escrito

  • src/main/site/markdown/indice.md
  • src/main/site/markdown/download.md
  • src/main/site/markdown/ejemplos.md
  • src/main/site/markdown/licencia.md
  • src/main/site/markdown/desarrolladores.md

Puedes verlos en site src/site/markdown

Imagenes y otros recursos en el site[editar]

Lo hemos comentado para el logo, pero aquí lo ampliamos. Cualquier fichero que pongamos en src/site/resources se publicará en el site. Por tanto, podemos poner imágenes, ficheros CSS o javascript. Cualquier cosa que necesitemos para nuestro site. Por debajo de resources podemos organizarlo como queramos, por ejemplo, subdirectorios images, css, javascript. Estos subdirectorios se copiarán al site y le path relativo desde nuestro html para acceder a esos recursos será images/..., css/... o javascript/...

Informes propios de maven[editar]

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. Sin embargo, podemos no ponerlo y manualmente poner lo que nos interese. Así que puedes ver en site.xml que hay otro menú con los siguientes item: "Tests", "Cobertura", "Javadoc", "Fuentes" y "pmd.html".

Estos informes los generan los plugin maven correspondientes y el enlace es al fichero html que genera dicho informe. Para que se generen estos informes cuando ejecutemos mvn site, debemos añadirlos en nuestro pom.xml en la sección de <reporting> 

<project>
    ...
    <reporting>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-report-plugin</artifactId>
                <version>3.2.2</version>
            </plugin>
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.8.11</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.6.2</version>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jxr-plugin</artifactId>
                <version>3.3.1</version>
                <configuration>
                    <linkJavadoc>true</linkJavadoc>
                    <javadocDir>${project.build.directory}/site/apidocs/</javadocDir>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-pmd-plugin</artifactId>
                <version>3.21.2</version>
            </plugin>
        </plugins>
    </reporting>
    ...
</project>

{{Colorbox|contenido=Detalles sobre cómo configurar estos plugins:

Nombre, url y about del site[editar]

maven-site-plugin coge algunos datos del fichero pom.xml, entre ellos el name, la url y la description

<syntaxhighight lang="xml"> <project> 

   ...
   <name>maven-site-example</name>
   <description>Ejemplo de maven-site-plugin</description>
   <url>https://chuidiang.org</url>
   ...

</project> </syntaxhighlight>

Resultado final[editar]

La siguiente imagen muestra como quedaría nuestro sitio de ejemplo

Sitio personalizado generado por maven-site-plugin
Sitio personalizado generado por maven-site-plugin

maven site:run[editar]

El comando mvn site:run levanta un servidor web jetty con nuestro site desplegado. Puede servirnos para verlo de forma rápida mientras lo estamos editando.

Enlaces[editar]

Obtenido de «https://chuidiang.org/index.php?title=Crear_un_sitio_web_con_Maven&oldid=9086»