Plus loin avec le Maven Site

Fabian Piau | dimanche 4 avril 2010 - 22:29

Introduction

Si votre projet est mavenisé (comprenez sous Maven), il serait vraiment dommage de ne pas utiliser toutes les possibilités du Maven Site.

Bien configuré, il peut devenir rapidement la « vitrine » de votre projet en centralisant ses informations les plus utiles tout en gardant un effort de maintenance très faible. Les sites Maven sont de plus en plus utilisés dans les projets open source.

Cela peut être des informations générales sur le projet (description, équipe, dépendances…), des sous-rapports spécifiques (Checkstyle, PMD, Javadoc, SureFire, Cobertura…), une FAQ (Frequently Asked Questions) sur le projet, bref ce que vous voulez…

Ce tutoriel va vous apprendre à personnaliser le site de base généré par Maven.

Prérequis : Maven doit être installé sur votre machine.

Version utilisée : 2.0.9. Suivant les versions, les commandes peuvent être différentes.

Création du projet

Tout au long du tutoriel, nous allons utiliser un projet Maven 2 de test généré grâce au plugin Archetype.

Dans un terminal, tapez :

mvn archetype:generate

Choisissez le modèle « maven-archetype-site ». Il permet de générer une structure complète de site.

Archetype vous demande plusieurs informations :

Le groupId du projet : demo.mavensite.personalization;
L’artifactId : maven-site-personalization;
La version : Appuyez directement sur Entrée, la version 1.0-SNAPSHOT nous convient;
Le package où mettre les classes : Par défaut, il reprend l’artifactId. C’est parfait, appuyez donc sur Entrée.

Un récapitulatif s’affiche, validez vos choix en appuyant sur Entrée une dernière fois.

Le projet est maintenant créé.

Parcours rapide du projet créé

Un dossier a été créé portant le nom « maven-site-personalization » .

Voici son architecture :

Un dossier « fr »? Et oui! Le Maven Site supporte l’internationalisation. Par défaut, celui généré par Archetype est disponible en anglais (langue par défaut) et en français.

Voici une description des différents fichiers créés.

site.xml : Le descripteur de site. Il définit le site dans son ensemble (la bannière, le menu à gauche, les liens disponibles). C’est en quelque sorte le point d’entrée de la génération;
site_fr.xml : Le descripteur pour la version française;
Tous les autres fichiers représentent une page du site. Pas d’HTML ici, les pages sont écrites dans des formats spécifiques à Maven qui serviront ensuite à générer du HTML.

Le site d’exemple reprend les 3 différents formats possibles (APT, Xdoc et FML).

Format Xdoc : C’est un format XML, ce format est disponible depuis les versions 1.x de Maven;
Format APT « Almost Plain Text » : Désigné remplaçant du Xdoc, ce format de type wiki est beaucoup moins verbeux;
Format FML : C’est le format utilisé pour créer des FAQ.

Génération du site

Après cette analyse de structure, nous allons générer le site à l’aide de la commande :

mvn site

mvn site:run

pour le lancer en local avec le serveur Jetty.

Le site généré est disponible dans /target/site/index.html (ou http://localhost:8080 si vous avez choisi Jetty)

Le Maven Site généré

Il s’agit du site par défaut. Pour accéder à la version française modifiez le chemin par /site/fr/index.html (ou http://localhost:8080/fr).

Un peu contraignant ce changement de langue, n’est-ce pas?

Nous allons voir juste après comment ajouter des liens pour naviguer facilement entre les 2 langues.

Ajout d’une page

Pour ajouter une nouvelle page au site, il suffit d’ajouter un fichier dans un des 3 dossiers

( « apt », « fml » ou « xdoc » ).

Par exemple, j’ai ajouté le fichier « my_new_category.apt » contenant un texte bien formaté dans le dossier « apt ».

Il faut ensuite le référencer dans le descripteur de site.

<?xml version='1.0' encoding='ISO-8859-1'?>
<project name='Maven'>
  <bannerLeft>
    <name>Maven</name>
    <src>http://maven.apache.org/images/apache-maven-project.png</src>
    <href>http://maven.apache.org/</href>
  </bannerLeft>
  <bannerRight>
    <src>http://maven.apache.org/images/maven-small.gif</src>
  </bannerRight>
  <body>
    <links>
      <item name='Apache' href='http://www.apache.org/' />
      <item name='Maven 1.0' href='http://maven.apache.org/'/>
      <item name='Maven 2' href='http://maven.apache.org/maven2/'/>
    </links>
    <menu name='Maven 2.0'>
      <item name='APT Format' href='format.html'/>
      <item name='FAQ' href='faq.html'/>
      <item name='Xdoc Example' href='xdoc.html'/>
      <item name='My new category' href='my_new_category.html'/>	  
    </menu>
  </body>
</project>

Relancez la génération du site

mvn clean site

et un nouvel item apparait dans le menu dirigeant vers votre nouvelle page.

Ajout d'une nouvelle page

J’en ai profité pour vous montrer les différentes fonctionnalités d’ATP (tableaux, liste, titres, formatage de texte…)

Internationaliser son site facilement

Nous allons ajouter des liens pour changer la langue.

Dans site.xml :

<project name='Maven'>
  [...]
  <body>
    [...]
    <menu name='Other languages'>
      <item name='Français' href='/fr/index.html'/> 
    </menu>
  </body>
</project>

Dans site_fr.xml :

<project name='Maven'>
  [...]
  <body>
    [...]
    <menu name='Autres langues'>
      <item name='English' href='../index.html'/> 
    </menu>
  </body>
</project>

Internationalisation du site

Par défaut, l’anglais est la langue principale. Pour modifier cela, il faut modifier le POM du projet.

fr

Le français est la seule langue disponible.

en,fr

L’anglais est la langue par défaut, le français est disponible.

fr,en

Le français est la langue par défaut, l’anglais est disponible.

fr,en,es,de

Le site est multilingue, disponible également en espagnol et en allemand.

Ajouter les rapports par défaut

Comme on peut le constater, il est très simple d’ajouter des pages et de modifier la structure du site.

Vous remarquerez que les différents rapports Maven par défaut (informations générales sur le projet) ne sont pas inclus dans le site.

Il vous suffit d’ajouter la balise :

<project>
  [...]
  <body>
    [...]
    <menu ref='reports'/>
  </body>
</project>

Les rapports par défaut

Autres modifications du contenu

Il existe d’autres possibilités de personnalisation en modifiant uniquement le descripteur :

Ajouter des liens dans la bannière;
Changer le titre de la fenêtre;
Modifier la position de la date de publication;
Modifier le logo « Built by Maven », les images dans la bannière…;
Afficher la version du logiciel (dans notre cas, la 1.0-SNAPSHOT);
etc.

Vous pouvez consulter toutes les informations sur le descripteur de site.

Changer le design du site avec des « skins »

Il est également possible de changer l’interface graphique générale du site.

Pour cela, il suffit (une fois de plus) de modifier le descripteur du projet (pas le POM) en ajoutant :

<project>
  [...]
  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-stylus-skin</artifactId>
    <version>1.2</version>
  </skin>
  [...]
</project>

Malheureusement, peu de thèmes sont disponibles. A l’heure où j’écris cet article, 3 thèmes officiels seulement existent.

maven-classic-skin (ancien thème, version 1.0);
maven-default-skin (thème par défaut, version 1.0);
maven-stylus-skin (thème utilisé par le site officiel, version 1.2).

Classic-site-skin

Default-site-skin

Stylus-site-skin

En recherchant un peu sur internet, vous réussirez à en trouver quelques autres.

En plus du contenu, il est tout à fait possible d’avoir des skins différents pour les versions française et anglaise (car 2 descripteurs de site différent).

Aller plus loin dans la personnalisation

Pour obtenir un site à votre image, il est possible d’aller encore plus loin en modifiant soit même le design.

Il est possible d’ajouter vos propres images, vos fichiers de style CSS respectant votre charte graphique, vos liens spécifiques sur le projet… et ainsi à ne pas vous limiter aux fonctions de base.

Ensuite et si le résultat vous convient, vous pourrez packager vos modifications et les rendre disponibles sous forme de skin.

Voici une sélection de designs que j’ai pu apprécier. Il faut dire que le résultat est plutôt réussi pour certains. On en oublierait presque qu’il s’agit d’un Maven Site…