Dans les chapitres précédents, nous avons vu comment utiliser Maven pour
construire votre projet
gérer ses dépendances
et générer les livrables
Dans ce chapitre, je vais vous montrer qu'il est aussi possible d'utiliser Maven pour générer un site web pour votre projet. Vous y retrouverez :
des informations générales sur celui-ci,
la Javadoc,
des rapports sur l'exécution des tests, la qualité du code...
Je vous montrerai également comment y ajouter vos propres éléments.
Allons-y.
Configuration de base du site
Convention sur l'arborescence
Par convention, les sources servant à la génération du site du projet se trouvent dans le répertoire src/site, lui-même organisé de cette manière :
🗁 src
└── 🗁 site
├── 🗁 apt
│ ├── 🗎 xxx.apt
│ └── ...
├── 🗁 fml
│ ├── 🗎 faq.fml
│ └── ...
├── 🗁 markdown
│ ├── 🗎 yyy.md
│ └── ...
├── 🗁 ...
├── 🗁 resources
│ ├── 🗁 css
│ │ └── 🗎 style.css
│ ├── 🗁 img
│ │ ├── 🗎 zzz.png
│ │ └── ...
│ └── ...
└── 🗎 site.xmlPas de panique, voici quelques explications :
Le fichier
src/site/site.xmlest le site descriptor. Il permet de définir la structure du site.Les répertoires
apt,markdown,fml... hébergent les fichiers source des pages du site qui seront converties en HTML par Maven. Ces répertoires accueillent des fichiers de leur format respectif :apt: Format Almost Plain Textfml: Format FAQ Markup Languagemarkdown: Format Markdown
Le répertoire
resourcespour les autres ressources :css/style.css: fichier CSS permettant d'ajuster le style par défaut...
Le site descriptor
Le fichier src/site/site.xml est le site descriptor. Il permet de définir la structure du site.
Je crée donc ce fichier site.xml :
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/DECORATION/1.7.0"
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0 http://maven.apache.org/xsd/decoration-1.7.0.xsd">
<!-- Utilisation du template de site fluido -->
<skin>
<groupId>org.apache.maven.skins</groupId>
<artifactId>maven-fluido-skin</artifactId>
<version>1.6</version>
</skin>
<!-- Affichage de la date et de la version à droite dans le bandeau du haut -->
<publishDate position="right"/>
<version position="right"/>
<body>
<!-- Ajout d'un fil d'ariane -->
<breadcrumbs>
<item name="Accueil" href="index.html"/>
</breadcrumbs>
<!-- ===== Menus ===== -->
<!-- Ajout d'un menu vers le projet parent -->
<menu ref="parent" inherit="top"/>
<!-- Ajout d'un menu vers les différents modules du projet -->
<menu ref="modules" inherit="top"/>
</body>
</project>Configuration du site dans le POM
Il faut ensuite ajouter dans le POM parent les informations de déploiement du site.
<project>
<!-- =============================================================== -->
<!-- DistributionManagement -->
<!-- =============================================================== -->
<distributionManagement>
<site>
<id>site-projet</id>
<url>scp://exemple.org/www/</url>
</site>
</distributionManagement>
...
</project>Générer le site
Ajout du plugin maven-site-plugin
Afin de générer le site, vous allez utiliser le plugin maven-site-plugin.
Vous ajoutez le plugin dans la section <pluginManagement> du POM parent :
<project>
...
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.6</version>
<configuration>
<!-- Je veux le site en français -->
<locales>fr</locales>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
...
</project>Génération du site
Pour générer le site, nous allons utiliser le build lifecycle site.
Étant donné qu'il s'agit d'un projet multi-module, la génération du site est un peu plus complexe que pour un projet simple. En effet, il va falloir que Maven :
génère un site pour le projet parent et pour chaque module (cela correspond au goal site du plugin maven-site-plugin)
agrège tous ces sites en un seul.
Cette dernière étape est réalisée automatiquement dans la phase site-deploy, via le goal deploy. Cependant vous ne voulez peut-être pas déployer le site, soit pour vous rendre compte avant du résultat, soit pour obtenir le site agrégé et le tester avant de le déployer. Cela est possible grâce au goal stage. Par défaut, ce goal génère le site agrégé dans le répertoire target/staging.
Allons-y, générons le site agrégé :
cd /chemin/vers/projet/parent mvn package site site:stage
Vous remarquez que j'enchaîne ici 3 exécutions :
la phase
packagela phase
sitele goal
site:stage
Il ne vous reste plus qu'à ouvrir le fichier target/staging/index.html :
Ajouter des pages personnalisées
Maintenant que vous savez générer le site, ajoutons-y vos propres pages.
C'est ici que vous allez utiliser les dossiers apt, fml, markdown...
Je vous propose d'ajouter 2 pages dans le site :
une page de documentation expliquant comment est organisé le projet
une foire aux questions
Ajout d'une page
Pour la page de documentation, je vais utiliser le format Markdown.
Je crée donc le répertoire src/site/markdown, et j'y crée un fichier architecture.md :
## Architecture du projet
### Généralités
Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Une image :
### L'application web
Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
### Les batches
Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.Enfin, j'ajoute une entrée de menu dans le site descriptor pour pouvoir accéder à cette page :
<project>
...
<body>
...
<!-- ===== Menus ===== -->
<!-- Ajout d'un menu vers la documentation -->
<menu name="Documentation">
<!-- Entrée de menu vers la page Architecture -->
<item name="Architecture" href="architecture.html"/>
</menu>
</body>
</project>Il ne reste plus qu'à relancer la génération du site pour obtenir les éléments que nous venons d'ajouter.
mvn package site site:stage
Ajout d'une FAQ
Pour ajouter une page de Foire aux questions, il suffit de suivre la même démarche que pour l'ajout d'une page, sauf que vous pouvez utiliser le format FAQ Markup Language, plus adapté à l'écriture d'une FAQ.
Je crée le fichier src/site/fml/faq.fml :
<?xml version="1.0" encoding="UTF-8"?>
<faqs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/FML/1.0.1"
xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
title="Foire Aux Questions"
toplink="false">
<part id="general">
<title>Général</title>
<faq id="why-x">
<question>
Pourquoi ... ?
</question>
<answer>
<p>
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam aperiam architecto assumenda
consequuntur delectus deleniti dolores dolorum ex excepturi explicabo ipsa, labore magnam maxime,
modi
nemo sint, sit veniam voluptate.
</p>
<p>...</p>
</answer>
</faq>
<faq id="how-x">
<question>
Comment ... ?
</question>
<answer>
<p>...</p>
</answer>
</faq>
</part>
<part id="install">
<title>Installation</title>
<faq id="how-install">
<question>
Comment installer ... ?
</question>
<answer>
<p>
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam aperiam architecto assumenda
consequuntur delectus deleniti dolores dolorum ex excepturi explicabo ipsa, labore magnam maxime,
modi
nemo sint, sit veniam voluptate.
</p>
<source>apt-get install xxx</source>
</answer>
</faq>
</part>
</faqs>J'ajoute une entrée de menu dans le site descriptor pour pouvoir accéder à cette FAQ :
<project>
...
<body>
...
<!-- ===== Menus ===== -->
<!-- Ajout d'un menu vers la documentation -->
<menu name="Documentation">
<!-- Entrée de menu vers la page Architecture -->
<item name="Architecture" href="architecture.html"/>
<!-- Entrée de menu vers la page FAQ -->
<item name="FAQ" href="faq.html"/>
</menu>
</body>
</project>Générez des rapports
https://maven.apache.org/plugins/maven-site-plugin/examples/configuring-reports.html
Rapports de base
Maven permet de générer, de base, un certain nombre de rapports sur votre projet :
Projet :
résumé du projet (nom, version, description, organisation...)
liste des modules du projet
membres du projet (contributeur, développeurs...)
licence du projet (section
<licenses>)gestion de la distribution du projet (section
<distributionManagement>)listes de diffusion (section
<mailingLists>)dépôt des sources du projet (section
<scm>)intégration continue (section
<ciManagement>)gestion des anomalies (section
<issueManagement>)
Plugins :
gestion des plugins (section
<pluginManagement>)liste des plugins utilisés dans le projet/module
Dépendances :
gestion des dépendances (section
<dependencyManagement>)liste des dépendances utilsées dans le projet/module
convergence des dépendances entre les différents modules du projet
Pour ajouter ces rapports au site, il faut ajouter un menu dans le fichier site.xml :
<project>
...
<body>
...
<!-- ===== Menus ===== -->
<!-- Ajout d'un menu vers les différents rapport -->
<menu ref="reports" inherit="top"/>
</body>
</project>Il faut également ajouter le plugin de génération des rapports dans le POM parent.
<project>
...
<!-- =============================================================== -->
<!-- Gestion des rapports -->
<!-- =============================================================== -->
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.7</version>
</plugin>
</plugins>
</reporting>
</project>Après regénération du site voici ce que cela donne :
Sélectionner certains rapports seulement
Il existe d'autres plugins permettant de créer des rapports. Chaque rapport est fourni par un goal d'un de ces plugins. Par défaut, quand vous ajoutez un plugin de rapport, tous ses goals sont exécutés, donc tous les rapports sont générés. Si vous le souhaitez, vous pouvez ne lancer que certains goals en ajoutant une section <reportSets> :
<project>
...
<!-- =============================================================== -->
<!-- Gestion des rapports -->
<!-- =============================================================== -->
<reporting>
<plugins>
<!-- ===== Rapport d'information général sur le projet ===== -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.7</version>
<reportSets>
<reportSet>
<reports>
<report>index</report>
<report>summary</report>
<report>plugins</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
</project>Ajouter d'autres rapports
Pour générer des rapports supplémentaires, il suffit d'ajouter les plugins correspondants : Liste des plugins (les plugin de rapports sont noté Type : R)
Par exemple, pour générer un rapport sur les tests :
<project>
...
<!-- =============================================================== -->
<!-- Gestion des rapports -->
<!-- =============================================================== -->
<reporting>
<plugins>
...
<!-- ===== Rapport sur les tests ===== -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-report-plugin</artifactId>
<version>2.20</version>
<configuration>
<linkXRef>false</linkXRef>
</configuration>
<reportSets>
<reportSet>
<reports>
<report>report-only</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
</project>
Vous remarquez ici qu'aucun test n'a été exécuté. En effet, les rapports sont générés par projet/modules. Le projet parent ne contient aucun test, seuls ses modules en contiennent ; je n'ai donc aucun test affiché ici.
Que diriez-vous d'avoir ici un affichage global de tous les tests de tous les modules ? Pour le moment, il n'y a rien… Eh bien, c'est possible grâce à l'agrégation de rapports.
Agréger des rapports
Certains plugins de rapport permettent d'agréger les rapports des modules au niveau du projet parent.
J'ajoute pour cela un deuxième reportSet :
<project>
...
<!-- =============================================================== -->
<!-- Gestion des rapports -->
<!-- =============================================================== -->
<reporting>
<plugins>
...
<!-- ===== Rapport sur les tests ===== -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-report-plugin</artifactId>
<version>2.20</version>
<configuration>
<linkXRef>false</linkXRef>
</configuration>
<!-- reportSet d'agrégation des rapports des sous-projets (modules) -->
<reportSet>
<id>aggregate</id>
<reports>
<report>report</report>
</reports>
<!-- ne pas exécuter ce sous-rapport dans les sous-projets -->
<inherited>false</inherited>
<configuration>
<aggregate>true</aggregate>
</configuration>
</reportSet>
<!-- reportSet non agrégé, exécuté dans tous les sous-projets (modules) -->
<reportSet>
<id>modules</id>
<!-- exécuter ce sous-rapport dans les sous-projets -->
<inherited>true</inherited>
<reports>
<report>report</report>
</reports>
<configuration>
<aggregate>false</aggregate>
</configuration>
</reportSet>
</plugin>
</plugins>
</reporting>
</project>J'obtiens ainsi :
le rapport agrégé dans le projet parent
le rapport « normal » dans chaque module
Pour la génération de la Javadoc, la configuration serait celle-ci :
<project>
...
<!-- =============================================================== -->
<!-- Gestion des rapports -->
<!-- =============================================================== -->
<reporting>
<plugins>
...
<!-- ===== Génération de la Javadoc ===== -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
<quiet>true</quiet>
<locale>fr</locale>
</configuration>
<reportSets>
<!-- reportSet exécuté dans tous les modules -->
<reportSet>
<reports>
<report>javadoc</report>
</reports>
</reportSet>
<!-- reportSet d'agrégation des rapports des sous-modules -->
<reportSet>
<id>aggregate</id>
<inherited>false</inherited>
<reports>
<report>aggregate</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
</project>Je vous ai gardé le meilleur pour la fin : un rapport sur la qualité du code avec Checkstyle :
<project>
...
<reporting>
<plugins>
...
<!-- ===== Rapport d'analyse du code par Checkstyle ===== -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>2.17</version>
<configuration>
<configLocation>src/build/checkstyle.xml</configLocation>
<linkXRef>false</linkXRef>
</configuration>
<reportSets>
<!-- reportSet exécuté dans tous les modules -->
<reportSet>
<reports>
<report>checkstyle</report>
</reports>
</reportSet>
<!-- reportSet d'agrégation des rapports des sous-modules -->
<reportSet>
<id>checkstyle-aggregate</id>
<inherited>false</inherited>
<configuration>
<skipExec>true</skipExec>
</configuration>
<reports>
<report>checkstyle-aggregate</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
</project>
Résumons
Maven permet de générer un site pour le projet. Utilisez pour cela la commande
mvn package site site:stage.Par convention, les sources servant à la génération du site du projet se trouvent dans le répertoire
src/site.La description du site se fait grâce au site descriptor : fichier
src/site/site.xml.Vous pouvez ajouter des ressources dans le répertoire
src/site/resources.Vous pouvez ajouter vos propres pages en utilisant des fichiers aux formats APT, FML, Markdown...
Vous pouvez générer des rapports en ajoutant des plugins de rapport dans la section
<reporting>.Vous pouvez configurer et agréger des rapports grâce aux sections
<reportSet>.
N'hésitez pas à consulter la documentation pour approfondir ce sujet et découvrir la multitude de choses réalisables :
Le mot de la fin
Voilà, nous arrivons au bout de ce cours sur Apache Maven. Vous en avez fini avec le temps perdu sur toutes les opérations manuelles comme la compilation, le packaging ou l'ajout de bibliothèques tierces...
Grâce à Maven, vous pouvez désormais gérer facilement les dépendances de votre projet. Vous êtes capable d'automatiser sa construction mais également la génération de vos différents livrables et même un site web sur votre projet.
Ressources
Vous pouvez retrouver les ressources utilisées dans ce cours, comme le projet de gestion de tickets, sur github :
