La génération de site avec Maven
… Maven offre la fonctionnalité très appréciable de génération automatisée du site web de votre projet Java/J2EE.
Il est de plus en plus fréquent de voir des sites de frameworks, librairies ou projets utilisés cette fonctionnalité comme le propre site de Maven, le site de Struts ou celui de Tapestry. Notez tout de même que ces trois exemples sont des projets Apache.
L’avantage principal de la génération de site par Maven est la possibilité d’utiliser des plugins permettant la génération de rapports liés à votre projet : rapport checkstyle et PMD, mise en ligne automatique de la Javadoc, afficher les sources en ligne, le résultat des tests unitaires, la couverture des tests unitaires de votre code, etc.
Pour commencer, il vous faut donc ajouter ces plugins dans le pom.xml principal de votre projet.
Voici la marche à suivre pour obtenir les rapports checkstyle, la Javadoc, les résultats des tests unitaires avec surefire, la couverture des tests unitaires avec Cobertura et la possibilité de visualiser les sources en ligne avec JXR :
<build> <plugins> ... <plugin> <groupId> org.codehaus.mojo </groupId> <artifactId> cobertura-maven-plugin </artifactId> <executions> <execution> <goals> <goal> clean </goal> </goals> </execution> </executions> </plugin> ... </plugins> ... </build> <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <configuration> <aggregate>true</aggregate> </configuration> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-checkstyle-plugin</artifactId> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jxr-plugin</artifactId> </plugin> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>cobertura-maven-plugin</artifactId> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-report-plugin</artifactId> <version>2.4.3</version> </plugin> </plugins> </reporting>
Lorsque nous exécuterons la commande de génération de code, des pages HTML liées à ces différents rapports seront générées automatiquement.
Mais avant d’en arriver à cette étape, il nous est nécessaire de mettre en place le fichier de configuration et description de notre future site Maven.
Il faut créer un fichier site.xml dans un répertoire src/site/ sur votre projet. Ce fichier va vous permettre de gérer les menus du site et les différentes pages que vous souhaitez mettre en place.
Cette étape n’est pas obligatoire. Il est possible de générer automatiquement un site très simplement en ajoutant quelques informations dans le pom.xml et en profitant de celles que vous avez déjà fournies, mais le résultat est sommaire.
Voici un exemple simple d’un fichier site.xml pour un projet classique :
<?xml version="1.0" encoding="ISO-8859-1"?> <project name="Nom du projet"> <publishDate position="none" /> <version position="none" /> <body> <menu name="Général"> <item name="Introduction" href="index.html" /> <item name="Structure du projet" href="structure.html" /> <item name="Concepts de développement" href="concepts.html" /> <item name="Evolution du projet" href="evolutions.html" /> </menu> <menu name="Documentation du projet"> <item name="Informations" href="informations.html" collapse="true"> <item name="Résumé du projet" href="project-summary.html"/> <item name="Equipe du projet" href="team-list.html"/> <item name="Dépendances" href="dependencies.html"/> <item name="Management des Plugins" href="plugin-management.html"/> <item name="Plugins du projet" href="plugins.html"/> </item> <item name="Rapports" href="rapports.html" collapse="true"> <item name="JavaDocs" href="apidocs/index.html"/> <item name="JavaDocs des Tests" href="testapidocs/index.html"/> <item name="Accès aux sources" href="xref/index.html"/> <item name="Accès aux sources de tests" href="xref-test/index.html"/> <item name="Tests unitaires" href="surefire-report.html"/> <item name="Couverture des tests unitaires" href="cobertura/index.html"/> <item name="Checkstyle" href="checkstyle.html"/> </item> </menu> </body> </project>
Dans ce fichier, tous les fichiers HTML liés aux rapports sont générés automatiquement par Maven lors de l’étape de génération du site.
Il reste donc à écrire les pages “internes” comme project_summary.html, par exemple.
Pour se faire, nous allons utiliser le format type wiki APT, proposé par Maven 2 pour une écriture plus simple et plus rapide. Les fichiers APT doivent être positionnés dans le répertoire src/site/apt/ de votre projet. Lors de la génération du site, les fichiers APT sont analysés par Maven, qui génère alors les fichiers HTML correspondant.
Voici en exemple (qui vous resservira peut-être), l’écriture du fichier rapports.apt permettant de pointer sur les différents rapports générés :
----------------
Rapports générés
----------------
Rapports générés
*----+------+
|| Document || Description |
*----+------+
| {{{./apidocs/index.html}JavaDocs}} | Documentation de l'API avec les JavaDocs |
*----+------+
| {{{./testapidocs/index.html}JavaDocs des Tests}} | Documentation de l'API des tests avec les JavaDocs |
*----+------+
| {{{./xref/index.html}Accès aux sources}} | Accéder aux sources du projet au format HTML |
*----+------+
| {{{./xref-test/index.html}Accès aux sources de tests}} | Accéder aux sources de tests du projet au format HTML |
*----+------+
| {{{./surefire-report.html}Tests unitaires}} | Rapport des tests unitaires effectués sur le projet |
*----+------+
| {{{./checkstyle.html}Checkstyle}} | Rapport Checkstyle sur les conventions de codage |
*----+------+La syntaxe :
*----+------+ || Cellule titre colonne 1 || Cellule titre colonne 2 | *----+------+ | cellule1 | cellule2 | *----+------+ | cellule3 | cellule4 | *----+------+
permet de décrire une table HTML.
La syntaxe :
{{{./something.html}Something}}permet de mettre en place un lien HTML.
Pour plus d’informations sur la syntaxe APT, allez ici.
Une fois que vous aurez créé les différentes pages que vous souhaitez voir sur le site web de votre projet, il ne vous reste plus qu’à générer celui-ci.
Pour se faire, rien de plus simple. Rendez-vous à la racine du répertoire de votre projet (ou doit se trouver votre pom.xml normalement) puis lancez la commande :
mvn site
La totalité des pages HTML générées se trouve dans le répertoire /target/site/ du projet.
Il est d’ailleurs conseillé de supprimer complètement ce répertoire avant toute nouvelle génération.
J’ai déjà remarqué la “non-regénération” de pages existantes.
Pour voir le résultat, il ne vous reste plus qu’à lancer, dans votre navigateur, le fichier index.html se trouvant en racine du répertoire /target/site/.
Vous pouvez également préférer la commande :
mvn site:run
qui exécutera la génération du site et le lancera automatiquement sur un serveur Jetty sur localhost:8080.
Pour informations, le port est configurable. Plus d’informations ici.
Tags: maven
Merci Aj un bon petit article