Créer un site avec Maven 2

L'étape site ne fait pas tout à fait partie du cycle de vie de base d'un projet Maven. Il est un peu à part et est fait des étapes suivantes :

• presite : exécute les différents processus nécessaires à la génération du site ;
• site : génère le site du projet ;
• postsite : prépare le site pour le déploiement ;
• site-deploy : déploie le site généré vers un serveur web.

Toutes ces étapes sont réalisées au moyen du plugin suivant :

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>2.0.1</version>
</plugin>

Ce plugin possède les goals suivants :

• site:site : permet de générer le site pour un projet. Les liens entre les modules ne vont pas fonctionner pour un projet multimodule ;
• site:deploy : déploie le site sur un serveur web ;
• site:run : lance le site en utilisant un serveur Jetty ;
• site:stage : génère le site localement comme s'il le déployait sur un serveur. Ce goal permet de tester si les liens entre modules fonctionnent correctement ;
• site:stage-deploy : déploie le site local vers un serveur web ;
• site:attach-descriptor : ajout le fichier de description du site (site.xml) dans la liste des éléments à déployer/installer ;
• site:jar : compresse la totalité du site dans un fichier .jar.

Dans cet article nous allons surtout nous intéresser aux goals site et deploy qui sont les plus importants pour la génération de site.

La première chose à faire est de renseigner les membres de l'équipe et les différents contributeurs de votre projet. Cela va permettre de générer une page spéciale « Membres du projet ».

Si on ne renseigne aucune information dans le POM, cette page va simplement indiquer qu'il n'y a personne de renseigné sur l'équipe du projet.

On va donc déclarer un développeur et un contributeur :

<developers>
    <developer>
        <id>wichtounet</id>
        <name>Baptiste Wicht</name>
        <email>baptistewicht@redaction-developpez.com</email>
        <url>http://baptiste-wicht.developpez.com</url>
        <organization>http://baptiste-wicht.developpez.com</organization>
        <organizationUrl>http://baptiste-wicht.developpez.com</organizationUrl>
        <roles>
            <role>Rédacteur</role>
            <role>Développeur</role>
        </roles>
        <timezone>1</timezone>
    </developer>
</developers>
 
<contributors>
    <contributor>
        <name>John Smith</name>
        <email>john@smith.com</email>
        <url>http://john.smith.com</url>
        <organization>Smith Corporation</organization>
        <organizationUrl>http://smith.com</organizationUrl>
        <roles>
            <role>Testeur</role>
        </roles>
        <timezone>-5</timezone>
    </contributor>
</contributors>

Et voici la page automatiquement générée par Maven :

Comme vous le voyez, c'est extrêmement simple de générer cette page. Si vous voulez ensuite rajouter un nouveau membre au projet ou un contributeur, il vous suffit de modifier votre XML et de régénérer le site.

Dans le site de base, vous trouvez aussi une page « Intégration continue ». De base, vous pouvez voir que cette page indique seulement qu'aucun système d'intégration continue n'est défini. Il est possible de renseigner les informations sur le serveur d'intégration continue utilisé dans le projet au moyen de l'élément <ciManagement> :

ciManagement>
    <system>continuum</system>
    <url>http://127.0.0.1:8080/continuum</url>
    <notifiers>
    <notifier>
            <type>mail</type>
            <address>chief-project@maven-article.com</address>
            <sendOnError>true</sendOnError>
            <sendOnFailure>true</sendOnFailure>
            <sendOnSuccess>false</sendOnSuccess>
            <sendOnWarning>false</sendOnWarning>
            <configuration>
                <address>continuum@maven-article.com</address>
            </configuration>
        </notifier>
    </notifiers>
</ciManagement>

Nous voyons donc qu'on peut renseigner le système utilisé, l'URL vers le serveur d'intégration continue ainsi que la configuration des notifiers, c'est-à-dire ce qui se passe lorsqu'un build est terminé. Dans notre cas, on indique que le serveur avertit chief-project@maven-article.com par email lorsqu'un build réussit ou échoue et l'adresse d'envoi est continuum@maven-article.com. Vous pouvez bien sûr renseigner plusieurs notifiers.

Voilà ce que donne la page une fois complétée :

Vous pouvez voir que Maven génère automatiquement l'adresse vers le système d'intégration continue, ici Apache Continuum, s'il le connaît.

Comme nous l'avons fait pour le système d'intégration continue, il est possible de donner des informations sur le gestionnaire de suivi des problèmes (bugtracker) du projet. De base, la page « Contrôle des livraisons » indique que rien n'a été renseigné pour le projet. On va donc renseigner ces informations au moyen de l'élément <issueManagement> :

<issueManagement>
    <system>Bugzilla</system>
    <url>http://www.maven-article.com/issues/</url>
</issueManagement>

Cette fois, on peut renseigner très peu d'informations sur le système utilisé. Une fois ces informations remplies et le site mis à jour, voilà ce que nous affiche la page « Contrôle des livraisons » :

La prochaine page qu'il est possible de générer est la page présentant la licence du projet. De base, cette page indique qu'aucune licence n'a été définie pour le projet. On va donc remédier à cela en configuration la licence dans le pom :

<licenses>
    <license>
        <name>GNU GPL V3</name>
        <url>http://www.gnu.org/licenses/gpl-3.0.html</url>
        <distribution>repo</distribution>
        <comments>Une license peu restrictive</comments>
    </license>
    <license>
        <name>Apache Software License, Version 2.0</name>
        <url>http://www.apache.org/licenses/LICENSE-2.0</url>
        <distribution>repo</distribution>
        <comments>La licence de Maven</comments>
    </license>
</licenses>

On a donc configuré deux licences pour le projet. Voilà ce que ça donne une fois le site mis à jour :

Comme vous le voyez, Maven récupère automatiquement le texte de la licence pour l'afficher sur la page.

De base, la page d'accueil du site affiche la description du projet. C'est pourquoi il est important de renseigner la description du projet :

<description>Article Maven est un projet d'article sur la génération de sites dans Maven 2. </description>

Et voici ce que donne la page d'accueil après cette modification :

Ensuite, il est également possible de renseigner des informations importantes sur le projet, c'est-à-dire sur l'organisation autour du projet. La page résumé présente ces informations. De base, elle n'est pas très intéressante.

On va donc renseigner quelques informations supplémentaires :

<url>http://baptiste-wicht.developpez.com/tutoriel/java/maven/site/projet</url>
 
<organization>
    <name>Baptiste Wicht Articles</name>
    <url>http://baptiste-wicht.developpez.com</url>
</organization>

Une fois le site mis à jour, voici ce que à quoi ressemble la nouvelle page résumé :

Comme vous le voyez, la page est déjà plus remplie. En plus de cela, vous pouvez voir que le copyright contient maintenant le nom de l'organisation en plus de l'année.

On va maintenant passer à la description du système de contrôle de sources (SCM) utilisé par le projet. Cela va permettre de remplir la page « Contrôle de sources ». Voici les informations importantes à entrer :

<scm>
    <connection>scm:svn:http://subversion.developpez.com/projets/JTheque/</connection>
    <url>http://subversion.developpez.com/projets/JTheque/</url>
    <tag>HEAD</tag>
</scm>

L'élément tag permet de spécifier le tag (version) courant du projet. Dans la plupart des cas, il s'agit de HEAD, c'est-à-dire qu'il s'agit du code présent sur la racine du SCM (donc hors d'une branche quelconque). L'élément connection permet de donner des informations sur l'URL de connexion au repository. Il faut toujours faire commencer cette URL par scm: suivi de l'abréviation de votre SCM et enfin l'adresse vers le repository. Finalement, url permet de spécifier une adresse vers un repository explorable par navigateur. Voilà ce que donne la page complétée :

Comme vous pouvez le constater, Maven génère automatiquement un mode d'emploi en fonction de votre système de gestion de sources en plus de fournir les liens vers le repository.

La dernière qu'on peut compléter en utilisant les informations du pom du projet, c'est la page « Listes de diffusion » qui présente les différentes listes de diffusion du projet. Voici un exemple de liste de diffusion :

<mailingLists>
    <mailingList>
        <name>Liste d'utilisateur</name>
        <subscribe>user-subscribe@maven-article.com</subscribe>
        <unsubscribe>user-unsubscribe@maven-article.com</unsubscribe>
        <post>user@maven-article.com</post>
        <archive>http://maven-article.com/user/</archive>
        <otherArchives>
            <otherArchive>http://archives.maven-article.com/mails/users</otherArchive>
        </otherArchives>
    </mailingList>
</mailingLists>

et voici la page qu'elle permet de générer :

Maven génère automatiquement des liens (mailto) vers les adresses sur lesquelles écrire pour s'inscrire, se désinscrire ou poster des messages sur la liste de diffusion.

Finalement, il y a aussi d'autres pages qui sont automatiquement gérées par Maven. Ce sont les suivantes :

• Dépendances : présente toutes les dépendances du projet ;
• Gestion des plugins : indique la gestion des plugins (pluginManagement) pour le projet ;
• Plugins du projet : liste les modules utilisés par le projet.

Ces pages se rempliront donc automatiquement au fur et à mesure que vous rajouterez des dépendances ou des plugins dans les phases de build ou de report.

En plus de permettre de changer la structure du site, le fichier site.xml permet aussi de changer le skin du site. Voilà les différents styles disponibles :

• Maven Default Skin : le skin par défaut, celui utilisé jusqu'à maintenant.
• Maven Classic Skin : le skin pour un site ressemblant à Maven 1 ;
• Maven Stylus Skin : un style plus moderne, utilisé sur le site de Maven par exemple ;

Voici comment utiliser chacun de ces skins. Il faut mettre le code XML présenté directement sous la racine du fichier site.xml.

Maven Classic Skin

<skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-classic-skin</artifactId>
    <version>1.0</version>
</skin>

Maven Stylus Skin

<skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-stylus-skin</artifactId>
    <version>1.0.1</version>
</skin>

À vous donc de trouver le skin que vous préférez. Vous pouvez également créer votre propre skin, mais nous ne traiterons par ce sujet. Si vous voulez en savoir plus sur la création de skin, le mieux est de lire la documentation de Mavenla documentation de Maven.

De base, Maven ne génère aucun lien entre les modules et le parent et vice-versa. On ne peut donc pas identifier directement qu'un projet a des sous-modules ou qu'un module a un parent. Néanmoins, Maven fournit des facilités pour générer de tels liens.

Liens vers les modules : Il est possible de générer automatiquement un menu présentant la liste des modules d'un projet avec les liens vers ces derniers avec le menu suivant :

<menu ref="modules"/>

Lien vers le projet parent : Il est possible de générer automatiquement un lien vers le projet parent :

<menu ref="parent"/>

Ce format permet de décrire des pages web de contenu dans un simple format texte. Le format utilisé est assez proche d'un format wiki et se veut très simple.

Ce format de fichier fonctionne par niveau d'indentation. Ce qui n'est pas indenté (ni espace ni tab à gauche du texte) est considéré comme des titres. Ce qui est ensuite indenté est considéré comme un paragraphe. Il est possible de créer des sections et sous-sections en utilisant le caractère étoile. Voici donc un exemple de fichier APT avec une certaine hiérarchie et des paragraphes :

1. Première partie
 
    Première ligne du paragraphe 1. 
    Seconde ligne du paragraphe 1. 
    Troisième ligne du paragraphe 1. 
 
    Première ligne du paragraphe 2. 
    Seconde ligne du paragraphe 2. 
 
* 1.1 On commence à descendre
 
    Pensez à prendre une lampe la prochaine. 
 
** 1.1.1 Et on descend
 
    Il commence à faire noir. 
 
*** 1.1.1.1 Encore 
 
    Il va faire tout noir. 
 
**** 1.1.1.1.1 Et encore
 
    J'ai peur !

Si on génère cette page avec par exemple test.apt, cela aura pour effet de créer une page test.html qui ressemblera à cela :

Ces pages respectent le format Maven et donc le skin qui est appliqué au site.

VII-A-1. Formatage▲

Le format APT ne permet pas un grand formatage des textes, c'est un format qui se veut simplifié. Voici ce qu'il est possible de faire :

• Italique : entourer le texte de < > ;
• Gras : entourer le texte de << >> ;
• Font monospaced : entourer le texte de <<< >>>.

Et voici un exemple intégrant ces trois formatages :

 

Sélectionnez

Formatage 
 
    Un peu de gras sur <<lui>>. De l'italique sur <moi> et pour finir <<<monsieur>>> utilise une police de caractères monospaced.

Voici le rendu de cet exemple :

VII-A-2. Listes▲

Il est également possible de faire des listes à puces en utilisant le caractère * sur une ligne indentée :

 

Sélectionnez

Listes
 
    * Element 1
 
    * Element 2
 
        * Sous-élément 1
 
        * Sous-élément 2
 
    * Element 3
 
    []

L'élément [] permet de fermer la liste. En plus des listes à puces, vous pouvez utiliser des listes numérotées, pour cela, il vous faut remplacer le caractère * par :

• [[1]] : numérotation décimale : 1, 2, 3, 4, 5… ;
• [[a]] : numérotation alphabétique : a, b, c, d, e… ;
• [[A]] : numérotation alphabétique majuscule : A, B, C, D, E… ;
• [[i]] : numérotation romaine : i, ii; iii, iv, v… ;
• [[I]] : numérotation romaine majuscule : I, II, III, IV, V…

Vous pouvez très bien imbriquer des listes numérotées différentes les unes dans les autres :

 

Sélectionnez

Listes numérotées
 
    [[1]] Élément numéroté 1
 
        [[A]] Élément numéroté A. 
 
        [[B]] Élément numéroté B. 
 
    [[2]] Élément numéroté 2
 
    []

qui aura pour effet de générer la page suivante :

VII-A-3. Tableaux▲

On peut également ajouter des tableaux. Ce format est également aussi intuitif, il consiste en fait à dessiner simplement le tableau en format texte. Par exemple, si on fait une page de download :

 

Sélectionnez

Tableaux
 
*-------------------------*----------------+----------------:-----------------:
| Centered                | Left-aligned   | Right-aligned  | Right-aligned   |
|                         | Lien           | Checksum (MD5) | Checksum (SHA1) |
*-------------------------*----------------+----------------:-----------------:
| JTheque Utils 1.1.1 (jar)             | jtheque-utils-1.1.1.jar | jtheque-utils-1.1.1.jar.md5 | jtheque-utils-1.1.1.jar.sha1 | 
*-------------------------*----------------+----------------:-----------------:
| JTheque Utils 1.1.1 (Source tar.bz2)  | jtheque-utils-1.1.1-src.tar.bz2 | jtheque-utils-1.1.1-src.tar.bz2.md5 | jtheque-utils-1.1.1-src.tar.bz2.sha1 | 
*-------------------------*----------------+----------------:-----------------:
| Release Notes           | Versions.html                    | | |
*-------------------------*----------------+----------------:-----------------:

Quelques explications sont nécessaires pour bien comprendre le fonctionnement.

Le tableau doit automatiquement commencer par *--. Chaque cellule peut contenir autant de ligne que nécessaire. C'est la première ligne qui définit l'alignement des différentes colonnes. La deuxième * permet de centrer la première colonne, le + indique une colonne alignée à gauche et le : permet d'aligner à droite.

Le premier | ne permet pas seulement de rendre plus lisible le tableau, il permet de spécifier qu'il faut dessiner les lignes du tableau.

VII-A-4. Ancres et liens▲

{ancre}

{{ancre}}.
{{{ancre} Texte à afficher}}}

{{http://baptiste-wicht.developpez.com}}.
{{{http://baptiste-wicht.developpez.com} Mes articles}}

VII-A-5. Divers▲

=====================

Ce format permet de décrire une FAQ. Ce format est en fait un fichier XML qui décrit les questions. Au contraire du format APT, ce format n'utilise pas son propre format de formatage, mais utilise du HTML pour le formatage des questions.

Un exemple est la meilleure façon d'appréhender ce format très intuitif :

<?xml version="1.0" encoding="UTF-8"?>
<faqs title="Frequently Asked Questions">
    <part id="General">
        <faq id="utility">
            <question>Est-ce que ce projet est utile ? </question>
            <answer>
                <p>
                    Pas du tout. Ce n'est qu'un projet exemple. 
                </p>
            </answer>
        </faq>
        <faq id="article">
            <question>Qui est l'auteur de ce projet ? </question>
            <answer>
                <p>
                    Baptiste Wicht. 
                </p>
            </answer>
        </faq>
    </part>
    <part id="Article">
        <faq id="article">
            <question>Est-ce que l'article est utile ? </question>
            <answer>
                <p>
                    Oui. Il vous apprendra à créer et à personnaliser un site pour un projet Maven 2. 
                </p>
            </answer>
        </faq>
        <faq id="article">
            <question>De quoi traite cet article ? </question>
            <answer>
                <p>
                    Il traite de la génération de site dans Maven 2. 
                </p>
            </answer>
        </faq>
    </part>
</faqs>

Comme vous pouvez le voir, rien de très compliqué au niveau de la construction. On sépare les différentes questions (faq) dans différents groupes (part) et chaque Q/R est formée d'une question et d'une réponse. Voici ce que ça donne :

Un grand merci à Romain LinsolasProfil de Romain Linsolas pour ses relectures !