• 20 heures
  • Moyenne

Ce cours est visible gratuitement en ligne.

course.header.alt.is_video

course.header.alt.is_certifying

J'ai tout compris !

Mis à jour le 12/12/2019

Générez un site pour votre projet

Connectez-vous ou inscrivez-vous gratuitement pour bénéficier de toutes les fonctionnalités de ce cours !

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.xml

Pas de panique, voici quelques explications :

  • Le fichier src/site/site.xml est le site descriptor. Il permet de définir la structure du site.

  • Les répertoires aptmarkdownfml... 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 :

  • Le répertoire resources pour 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 <dependencyManagement> 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>
</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 :

  1. génère un site pour le projet parent et pour chaque module (cela correspond au goal site du plugin maven-site-plugin)

  2. 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 :

  1. la phase package

  2. la phase site

  3. le goal site:stage

Il ne vous reste plus qu'à ouvrir le fichier target/staging/index.html :

Aperçu du site
Aperçu du site

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 aptfmlmarkdown...

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 :
![Dépendances entre les modules](img/dependances_modules.png)
### 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
Aperçu de la nouvelle page du site
Aperçu de la nouvelle page du site

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 :

Aperçu des rapports
Aperçu des rapports

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>
Aperçu du rapport sur les tests
Aperçu du rapport sur les tests

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

Aperçu du rapport agrégé sur les tests
Aperçu du rapport agrégé sur les tests

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>
Aperçu du rapport agrégé de Checkstyle
Aperçu du rapport agrégé de Checkstyle

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 :

Exemple de certificat de réussite
Exemple de certificat de réussite