Créer un site avec Maven 2

Baptiste Wicht

Cet article va vous présenter la création d'un site web avec Maven 2.

Commentez ♪

- Titre : Créer un site avec Maven 2

- Auteur : Baptiste Wicht

- Parution : 12 septembre 2009

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2009 Baptiste Wicht. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- I-A. Cycle de vie « site »

- II. Site de base

- III. Internationalisation

- IV. Informations sur le projet

- IV-A. Membres du projet

- IV-B. Intégration continue

- IV-C. Gestion des demandes

- IV-D. Licence

- IV-E. Description et résumé du projet

- IV-F. Contrôle de sources

- IV-G. Listes de diffusion

- IV-H. Pages gérées par Maven

- V. Rapports de projet

- VI. Structure du site

- VI-A. Skins

- VI-B. Projets multimodules

- VII. Ajout de contenu

- VII-A. Format APT

- VII-A-1. Formatage

- VII-A-2. Listes

- VII-A-3. Tableaux

- VII-A-4. Ancres et liens

- VII-A-5. Divers

- VII-B. Format FML

- VIII. Déploiement du site

- IX. Conclusion

- IX-A. Remerciements

I - Introduction

Comme vous le savez peut-être, Maven 2 permet de générer un site web dans un format généralisé pour tout projet Maven 2.

Ce site est généré à partir des informations du fichier pom.xml, ainsi que d'après plusieurs fichiers écrits uniquement pour le site, comme nous le verrons par la suite.

Cet article ne nécessite pas de connaissances avancées de Maven 2, néanmoins, une connaissance de base peut être intéressante pour mieux comprendre les concepts expliqués dans cet article.

I-A - Cycle de vie « site »

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.

II - Site de base

On va commencer par définir un simple fichier pom.xml qu'on va enrichir au fur et à mesure de l'avancement dans ce tutoriel.

Voici le fichier pom.xml qui nous servira de base :

<project
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>
<groupId>com.developpez</groupId>
<artifactId>article-maven</artifactId>
<name>Article Maven</name>
<version>1.0</version>
</project>

C'est donc un fichier des plus basiques. On va ensuite ajouter un simple fichier Java dans le package com.developpez :

package com.developpez;

/**
* Un article Maven
*
* @author Baptiste Wicht
*/
public class ArticleMaven {
/**
* Méthode main.
*
* @param args Ignorés.
*/
public static void main(String[] args){
System.out.println(getDescription());
}

/**
* Retourne la description du projet.
*
* @return La description du projet.
*/
public static String getDescription(){
return "Je suis un article de Developpez";
}
}

Comme vous le voyez, c'est très simple comme classe Java. Nous ajoutons la méthode getDescription() afin d'écrire plus tard le test unitaire permettant de tester la classe Java.

Pour le moment, nous n'avons encore donné aucune information sur le site. Et pourtant, il est déjà possible de générer un site avec le peu d'informations disponibles comme le veut la philosophie Maven 2. Pour cela, il vous faut exécuter la commande suivante :

mvn site

qui devrait vous donner quelque chose du genre dans la console :

[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building Article Maven
[INFO]    task-segment: [site]
[INFO] ------------------------------------------------------------------------
[INFO] [site:site {execution: default-site}]
[WARNING] No URL defined for the project - decoration links will not be resolved
[INFO] Generating "About" report.
[INFO] Generating "Issue Tracking" report.
[INFO] Generating "Project Team" report.
[INFO] Generating "Dependencies" report.
[INFO] Generating "Continuous Integration" report.
[INFO] Generating "Source Repository" report.
[INFO] Generating "Project License" report.
[INFO] Generating "Mailing Lists" report.
[INFO] Generating "Plugin Management" report.
[INFO] Generating "Project Summary" report.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4 seconds
[INFO] Finished at: Sun Sep 13 15:13:16 CEST 2009
[INFO] Final Memory: 22M/63M
[INFO] ------------------------------------------------------------------------

Vous devriez normalement trouver un répertoire target/site dans votre projet. C'est dans ce dossier que sera généré le site. En ouvrant le fichier index.html, vous verrez s'afficher le site suivant :

Le site minimum

Vous pouvez voir que malgré le fait qu'on ait donné très peu d'informations sur le site, il y a déjà plusieurs pages sur notre site. En vous rendant sur ces différentes pages (en utilisant le menu de navigation de gauche), vous verrez que la plupart indiquent qu'il n'y a pas de contenu à afficher. On va remplir ces lacunes et ajouter de nouvelles pages au fur et à mesure de l'avancement dans cet article.

III - Internationalisation

Comme vous avez pu le voir, la version de base du site est entièrement en anglais. Il est néanmoins possible de changer cela. La configuration du plugin site permet en effet de spécifier une ou plusieurs locales avec lesquelles générer le site.

Si on veut passer le site en français, il suffit donc de configurer le plugin :

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>2.0.1</version>
<configuration>
<locales>fr</locales>
</configuration>
</plugin>
</plugins>
</build>

En générant à nouveau le site, vous obtiendrez cette fois un site en français :

Site de base en français

Il est également possible de gérer un site multilangue en renseignant une liste de locales séparées par des virgules. La première locale sera la version par défaut du site et les autres versions seront générées dans un sous-dossier du répertoire site. Par exemple, si vous renseignez les locales suivantes :

<locales>fr,en,it</locales>

Vous obtiendrez l'arborescence suivante :

target/site : Le site par défaut en français
en : le site en anglais
it : le site en italien

Comme vous le voyez, c'est très facile de générer un site multilangue. Il faut néanmoins savoir que tous les modules ne supportent pas le multilangue. Il faut également noter que Maven ne permet pas de générer automatiquement des liens vers d'autres langues, c'est donc à vous d'ajouter ces liens. Nous verrons comment plus tard.

Les prochaines captures d'écran seront toutes prises avec le site en français.

IV - Informations sur le projet

Maven 2 peut automatiquement générer des rapports en se basant sur les informations du projet. En remplissant votre fichier POM avec toutes les informations nécessaires, vous aurez déjà accès à de nombreuses pages ajoutées sur votre site.

IV-A - Membres du projet

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 :

Membres du projet

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.

IV-B - Intégration continue

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 :

Page Intégration continue

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.

IV-C - Gestion des demandes

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 » :

Gestion des demandes

IV-D - Licence

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 :

Page Licence du projet

Page Licence du projet

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

IV-E - Description et résumé du projet

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 :

Page d'accueil avec description du projet

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é :

Résumé du projet

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.

IV-F - Contrôle de sources

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 :

Page Dépôt de sources

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.

IV-G - Listes de diffusion

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 :

Listes de diffusion

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.

IV-H - Pages gérées par Maven

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.

V - Rapports de projet

En plus des rapports générés de base par Maven, il est possible d'inclure de nombreux autres rapports. Je vais en présenter quelques-uns ici, mais il en existe d'autres. Pour les ajouter, il suffit de rajouter leur plugin dans la section reporting du POM. Voici donc quelques rapports qu'il est possible d'ajouter.

Javadoc : permet de générer la Javadoc du projet sur le site dans le dossier apidocs.

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.6</version>
</plugin>

Javadoc du projet

PMD : permet de générer un rapport d'analyse PMD des classes Java.

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>2.4</version>
<configuration>
<targetJdk>1.6</targetJdk>
</configuration>
</plugin>

Rapport PMD

Comme vous pouvez le voir, cela permet également de générer le rapport CPD, qui permet de détecter les duplications dans votre code. Dans notre cas, bien sûr, aucun des deux rapports n'est très fourni ni très utile, mais dans le cas d'un gros projet, ce sont des rapports très intéressants.

Checkstyle : permet de générer un rapport d'analyse Checkstyle des classes Java.

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>2.3</version>
</plugin>

Là encore, pour notre projet, ce n'est pas un rapport des plus utiles.

Tests unitaires : on va maintenant passer aux rapports de tests unitaires. Pour cela, on va commencer par créer un test unitaire JUnit 4 très simple :

package com.developpez;

/**
* Un test pour l'article Maven.
*
* @author Baptiste Wicht
*/
public class ArticleMavenTest {
/**
* Teste la méthode getDescription().
*/
@Test
public void testGetDescription() {
assertEquals(ArticleMaven.getDescription(), "Je suis un article de Developpez");
}
}

Rien de plus bête comme test.

On va maintenant ajouter les rapports de surefire et de cobertura (couverture de code) :

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-report-plugin</artifactId>
<version>2.4.2</version>
</plugin>

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>cobertura-maven-plugin</artifactId>
<version>2.3</version>
</plugin>

Voilà ce que donne le rapport Surefire :

Rapport Surefire du projet

Rapport Surefire du projet

Et voilà ensuite ce que donne le rapport Cobertura de couverture de code :

Rapport Cobertura du projet

Le fait d'ajouter des classes de tests, fait que le plugin Javadoc génère directement la javadoc des classes de tests.

VI - Structure du site

En plus des informations contenues dans le pom.xml, on peut ajouter d'autres informations spécifiques au site dans le fichier site.xml qui doit se trouver dans le dossier src/site. Ce fichier permettra de gérer la structure du site ainsi que plusieurs informations sur le site (titre, skins).

On va donc voir au fur et à mesure comment configurer les différents éléments du fichier site.xml. On va commencer avec un fichier site.xml vide tel que celui-là :

<project name="Article Maven">

</project>

Vous verrez qu'on va commencer avec un site presque vide. Le fait de créer un site.xml écrase la configuration de base (le menu de gauche par exemple).

Positions de la date de publication et de la dernière version : La première qu'on peut configurer est la position de la date de publication et de la dernière version. On peut utiliser pour cela les positions suivantes :

- left ;

- right ;

- navigation-top ;

- navigation-bottom ;

- bottom.

On va donc mettre les deux à droite :

<publishDate position="right"/>
<version position="right"/>

Et voilà ce que donne notre site :

Date de publication et version

C'est tout ce qu'on peut changer pour le projet, ensuite, on peut modifier le corps du site (body) :

<project name="Article Maven">
...

<body>

</body>
</project>

Liens : Il est possible d'ajouter des liens supplémentaires dans la barre de navigation sur la droite :

<links>
<item name="Developpez.com" href="http://www.developpez.com"/>
<item name="Maven" href="http://maven.apache.org"/>
</links>

Liens

Navigation (breadcrumb) : Il est possible de configurer des éléments de navigation (breadcrumb) :

<breadcrumbs>
<item name="Mes articles" href="http://baptiste-wicht.developpez.com/"/>
<item name="Article Maven" href="http://baptiste-wicht.developpez.com/tutoriel/java/maven/site"/>
</breadcrumbs>

Navigation

Menu personnalisé : Il est également possible de créer ses propres menus menant vers des pages personnalisées (nous verrons comment créer ces pages dans le prochain chapitre) :

<menu name="Article Maven">
<item name="Télécharger" href="download.html"/>
<item name="FAQ" href="faq.html"/>
</menu>

Dans un site multilangue, il peut-être intéressant de mettre un lien vers les différentes versions, par exemple :

<menu name="Autres langues">
<item name="English" href="en/index.html"/>
<item name="Italiano" href="it/index.html"/>
</menu>

Menus personnalisés

Menus générés par Maven : Vous aurez certainement remarqué qu'avec toutes les modifications qu'on a apportées, on a perdu les liens vers les rapports de Maven 2. Il y a néanmoins deux solutions pour remédier à ce problème :

- ajouter les liens dans des menus personnalisés ;

- réintégrer les menus de base du site Maven.

On a déjà vu comment effectuer la première solution, on va voir comment mettre en œuvre la seconde. C'est en fait très simple :

<menu ref="reports"/>

On crée simplement un menu qui sera remplacé par les menus de rapports de base de Maven.

Menus de base de Maven

Dans le cas d'un site internationalisé, il faut également internationaliser le fichier site.xml. Par exemple pour un site en français, anglais et italien, on aura les fichiers site.xml, site_en.xml et site_it.xml.

VI-A - Skins

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 Classic Skin

Maven Stylus Skin

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

Maven Stylus 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 Maven.

VI-B - Projets multimodules

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"/>

Les liens entre les modules ne fonctionneront pas en local. Il faut déployer le site pour que ces liens soient correctement résolus. On peut également utiliser le goal site:stage pour que ces liens fonctionnent en local.

VII - Ajout de contenu

En plus des pages et des informations directement générées par Maven 2, il est possible d'ajouter des pages de contenu sous plusieurs formats :

- page au format APT : ce sont des simples pages de contenu. Ces fichiers doivent se trouver dans le dossier site/apt ;

- page au format FML : ce format permet de décrire des FAQ. Ces fichiers doivent se trouver dans le dossier site/fml.

Les pages seront ensuite générées au format HTML par Maven. Le nom du fichier sera le même, seule l'extension va changer.

Si la page au format .html existe déjà lors de la génération du site, Maven ne va pas régénérer la page même si vous avez modifié la page source (APT ou FML). Il est donc intéressant de faire un clean du projet avant de générer le site pour être sûr que toutes les pages seront régénérées.

VII-A - Format APT

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 :

Page au format APT

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 :

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 :

Texte formaté

VII-A-2 - Listes

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

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 :

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 :

Listes numérotées

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 :

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                    | | |
*-------------------------*----------------+----------------:-----------------:

Tableaux

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

On peut maintenant passer à la définition des liens et des ancres.

Premièrement pour définir une ancre, il suffit d'ajouter :

{ancre}

et remplacer ancre par le nom de l'ancre.

Pour un lien sur une ancre, on peut faire deux choses :

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

La première afficher simplement un lien avec le nom de l'ancre, le deuxième permet de changer le texte à afficher. Le principe est le même pour les liens :

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

VII-A-5 - Divers

Ligne horizontale : il est possible d'afficher une ligne horizontale en utilisant le code suivant :

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

Il suffit en fait de 3 caractères = pour que cela génère une ligne horizontale, mais avec plus de caractères, le fichier APT est plus lisible.

Saut de ligne : on peut également forcer un saut de ligne avec le code suivant \ suivi d'un saut de ligne.

Commentaires : on peut commenter une portion de code, en utilisant le caractère ~~.

VII-B - Format FML

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 :

FAQ sur le projet

VIII - Déploiement du site

Finalement, la dernière étape une fois que vous avez entièrement défini votre site est bien entendu de le déployer sur un serveur web pour le rendre accessible, soit à tous, soit à votre équipe de projet.

Pour commencer, il vous faudra déclarer un site sur lequel déployer le site. Voici un exemple qui utilise ftp :

pom.xml

<distributionManagement>
<site>
<id>bw-web-server</id>
<name>Baptiste Wicht FTP Server</name>
<url>ftp://baptiste-wicht.developpez.com/tutoriel/java/maven/site/projet</url>
</site>
</distributionManagement>

En plus de cela, il faut également enregistrer un ensemble clé/mot de passe dans le fichier settings.xml, pour cela, il faut y déclarer un nouveau serveur correspondant à l'id du serveur du site :

settings.xml

<server>
<id>bw-web-server</id>
<username>login</username>
<password>mdp</password>
</server>

Pour le déploiement par FTP, il faut enregistrer une extension permettant d'effectuer le déploiement par FTP :

pom.xml

<build>

...

<extensions>
<extension>
<groupId>org.apache.maven.wagon</groupId>
<artifactId>wagon-ftp</artifactId>
<version>1.0-beta-5</version>
</extension>
</extensions>

...

</build>

à la suite de quoi, il faut bien veiller à ce que l'url de votre projet corresponde bien à l'endroit où le site est généré, pour que les liens soient corrects. Vous pouvez finalement déployer le site avec la commande suivante :

mvn site:deploy

L'extension FTP ne permet pas de créer le dossier de base dans lequel est généré le site, c'est pourquoi il faut préalablement s'assurer que le dossier dans lequel le site sera généré existe bien.

Cette opération peut être assez longue en fonction de la taille du site et du nombre de pages à uploader, il faudra donc vous armer de patience. Dans le cas de ce projet, cela prend environ une minute sur ma connexion à 300 Ko/s d'upload.

Le goal deploy nécessite que le site soit préalablement généré avant de pouvoir l'uploader, il ne permet pas de générer le site. Si vous voulez générer le site et l'uploader, il vous suffit d'invoquer la phase site-deploy du cycle de vie directement.

Vous pouvez voir le site généré ici.

Pour utiliser une authentification avec clé, vous devez renseigner les éléments <privateKey> et <passphrase> du serveur dans settings.xml.

IX - Conclusion

En conclusion, vous avez pu voir qu'il est très simple de générer un site avec Maven 2. Cette façon de gérer un site a plusieurs avantages pour vous :

- vous vous concentrez sur le contenu, non pas sur la présentation ;

- le site est normalisé, la plupart des développeurs Java ont l'habitude de ce genre de site ;

- il est très facile de modifier ou de rajouter des informations ;

- etc.

Si vous voulez télécharger les fichiers qui ont servi à générer ce site, vous pouvez télécharger cette archive ZIP qui contient tous les fichiers nécessaires.

N'hésitez pas à commenter cet article : Commentez

IX-A - Remerciements

Un grand merci à Romain Linsolas pour ses relectures !