Maven Site

8/8/2019 Maven Site

http://slidepdf.com/reader/full/maven-site 1/38

Créer un site avec Maven 2

par Baptiste Wicht (Mon site) (Blog)

Date de publication : 12 septembre 2009

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

http://baptiste-wicht.developpez.com/blog

http://baptiste-wicht.developpez.com/

http://www.developpez.net/forums/u75080/baptiste-wicht/

http://www.developpez.com/

8/8/2019 Maven Site


Créer un site avec Maven 2 par Baptiste Wicht (Mon site) (Blog)

- 2 -Les sources présentées sur cette pages sont libres de droits, et vous pouvez les utiliser à votre convenance. Par contre la page de présentation deces sources constitue une oeuvre intellectuelle protégée par les droits d'auteurs. Copyright © 2009 - Baptiste Wicht. Aucune reproduction, mêmepartielle, 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'à 3 ans de prison et jusqu'à 300 000 E de dommages et intérêts.

http://baptiste-wicht.developpez.com/tutoriel/java/maven/site/

1 - Introduction................................................ ..................................................................... ........................................31.1 - Cycle de vie "site"......................................................................................................................................... 3

2 - Site de base...........................................................................................................................................................43 - Internationalisation................................................................................................................................................. 64 - Informations sur le projet.......................................................................................................................................8

4.1 - Membres du projet........................................................................................................................................ 8

4.2 - Intégration continue....................................................................................................................................... 94.3 - Gestion des demandes................................................................................................................................104.4 - Licence.........................................................................................................................................................114.5 - Description et résumé du projet.................................................................................................................. 134.6 - Contrôle de sources.................................................................................................................................... 154.7 - Listes de diffusion........................................................................................................................................164.8 - Pages gérées par Maven............................................................................................................................ 17

5 - Rapports de projet............................................................................................................................................... 186 - Structure du site...................................................................................................................................................22

6.1 - Skins............................................................................................................................................................ 256.2 - Projets multi-modules.................................................................................................................................. 28

7 - Ajout de contenu..................................................................................................................................................29

7.1 - Format APT................................................................................................................................................. 297.1.1 - Formatage........................................................................................................................................... 317.1.2 - Listes................................................................................................................................................... 317.1.3 - Tableaux.............................................................................................................................................. 327.1.4 - Ancres et liens.................................................................................................................................... 337.1.5 - Divers...................................................................................................................................................33

7.2 - Format FML................................................................................................................................................. 348 - Déploiement du site............................................................................................................................................. 369 - Conclusion............................................................................................................................................................38

9.1 - Remerciements............................................................................................................................................ 38








8/8/2019 Maven Site





1 - 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 projetMaven 2.

Ce site est généré à partir des informations du fichier pom.xml, ainsi que d'après plusieurs fichiers écrits uniquementpour 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.

1.1 - 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 faitdes étapes suivantes :

• pre-site : exécute les différents processus nécessaires à la génération du site• site : génère le site du projet• post-site : 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 multi-modules.

• 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 lagénération de site.







8/8/2019 Maven Site





2 - 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 dansce tutoriel.

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

<projectxmlns= "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.0http://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 packagecom.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'écrireplus 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éja 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 éxécuter la commande suivante :

mvn site

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

[INFO] Scanning for projects...







8/8/2019 Maven Site





[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épértoire 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éja plusieurs pages sur notre site. En vous rendant sur ces différentes pages (en utilisant le menu de navigation de gauche), vous verrezque la plupart indique qu'il n'y a pas de contenu à afficher. On va remplir ces lacunes et ajouter de nouvelles pagesau fur et à mesure de l'avancement dans cet article.








8/8/2019 Maven Site





3 - Internationalisation

Comme vous avez pu le voir, la version de base du site est entièrement en anglais. Il est néanmoins possible dechanger cela. La configuration du plugin site permet en effet de spécifier une ou plusieurs locales avec lesquellesgé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 multi-langues 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 duré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ç aisen : le site en anglais

it : le site en italien








8/8/2019 Maven Site





Comme vous le voyez, c'est très facile de géné rer un site multi-langues. Il faut néanmoins s avoir que tous les modulesne supportent pas le multi-langues. Il faut également noter que Maven ne permet pas de générer automatiquementdes 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.









8/8/2019 Maven Site





4 - Informations sur le projet

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

4.1 - 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 derenseigné 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> [email protected] </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> [email protected] </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 :







8/8/2019 Maven Site





Membres du projet

Comme vous le voyez, c'est extrêmement simple de générer cette page. Si vous voulez ensuite rajouter un nouveaumembre au projet ou un contributeur, il vous suffit de modifier votre XML et de regénérer le site.

4.2 - Intégration continue

Dans le site de base, vous trouvez aussi une page "Intégration continue". De base, vous pouvez voir que cette pageindique seulement qu'aucun système d'intégration continue n'est défini. Il est possible de renseigner les informationssur 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> [email protected] </address> <sendOnError> true </sendOnError> <sendOnFailure> true </sendOnFailure> <sendOnSuccess> false </sendOnSuccess> <sendOnWarning> false </sendOnWarning> <configuration> <address> [email protected] </address> </configuration> </notifier> </notifiers></ciManagement>







8/8/2019 Maven Site





Nous voyons donc qu'on peut renseigner le sy stème utilisé, l'URL vers le serveur d'intég ration continue ainsi que laconfiguration des notifiers, c'est-à-dire ce qui se passe lorsqu'un build est terminé. Dans notre cas, on indique que leserveur avertit [email protected] par email lorsqu'un build réussit ou échoue et l'adresse d'envoi [email protected]. Vous pouvez bien sûr renseigner plusieurs notifiers.

Voilà ce que donne la page une fois completé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 ApacheContinuum, s'il le connaît.

4.3 - Gestion des demandes

Comme nous l'avons fait pour le système d'intégration continue, il est possible de donner des informationssur 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>








8/8/2019 Maven Site





</issueManagement>

Cette fois, on peut renseigner très peu d'informations sur le système utilisé. Une fois ces informations remplies et lesite mis à jour, voilà ce que nous affiche la page "Contrôle des livraisons" :

Gestion des demandes

4.4 - 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 indiquequ'aucune license n'a été définie pour le projet. On va donc remédier à cela en configuration la license 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 :







8/8/2019 Maven Site





Page Licence du projet







8/8/2019 Maven Site





Page Licence du projet

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

4.5 - 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 ladescription du projet :

<description> Article Maven est un projet d'article sur la génération de sites da ns Maven2. </description>

Et voici ce que donne la page d'accueil après cette modification :








8/8/2019 Maven Site





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









8/8/2019 Maven Site





Résumé du projet

Comme vous le voyez, la page est déja plus remplie. En plus de cela, vous pouvez voir que le copyright contientmaintenant le nom de l'organisation en plus de l'année.

4.6 - Contrôle de sources

On va maintenant passer à la description du système de contrôle de sources (SCM) utilisé par le projet. Cela vapermettre 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







8/8/2019 Maven Site





permet de donner des informations sur l'URL d e connection au repository. Il faut toujours f aire commencer cette URLpar scm: suivi de l'abréviation de votre SCM et enfin l'adresse vers le repository. Finalement, url permet de specifier 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èmede gestion de sources en plus de fournir les liens vers le repository.

4.7 - 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" quiprésente les différentes listes de diffusion du projet. Voici un exemple de liste de diffusion :








8/8/2019 Maven Site





<mailingLists> <mailingList> <name> Liste d'utilisateur </name> <subscribe> [email protected] </subscribe> <unsubscribe> [email protected] </unsubscribe> <post> [email protected] </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 addresses sur lesquelles écrires pour s'inscrire, sedésinscrire ou poster des messages sur la liste de diffusion.

4.8 - 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 desplugins dans les phases de build ou de report.







8/8/2019 Maven Site





5 - 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 enprésenter quelques uns ici, mais il en existe d'autres. Pour les ajouter, il suffit de rajouter leur plugin dans la sectionreporting 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>







8/8/2019 Maven Site





Rapport PMD

Comme vous pouvez le voir, cela permet également de générer le rapport CPD, qui permet de détecter les duplicationsdans votre code. Dans notre cas, bien sûr, aucun des deux rapports n'est très fourni ni très utile, mais dans le casd'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>







8/8/2019 Maven Site





<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








8/8/2019 Maven Site





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.







8/8/2019 Maven Site





6 - Structure du site

En plus des informations contenues dans le pom.xml, on peut ajouter d'autres informations spécifiques au site dansle fichier site.xml qui doit se trouver dans le dossier src/site. Ce fichier permettra de gérer la structure du site ainsique 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 debase (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 positionde 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 à droites :

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







8/8/2019 Maven Site





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







8/8/2019 Maven Site





</menu>

Dans un site multilangue, il peut-être intéressant de mettre un lien vers les différents 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 2 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éja vu comment effectuer la première solution, on va voir comment mettre en oeuvre la seconde. C'est enfait très simple :

<menu ref= "reports" />

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







8/8/2019 Maven Site





Menus de base de Maven

Dans le cas d'un site internationalisé, il faut ég alement 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.

6.1 - 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>








8/8/2019 Maven Site





Maven Classic Skin

Maven Stylus Skin

<skin> <groupId> org.apache.maven.skins </groupId>

<artifactId> maven-stylus-skin </artifactId> <version> 1.0.1 </version></skin>







8/8/2019 Maven Site





Maven Stylus Skin

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


http://maven.apache.org/plugins/maven-site-plugin/examples/creatingskins.html

http://maven.apache.org/plugins/maven-site-plugin/examples/creatingskins.html






8/8/2019 Maven Site





6.2 - Projets multi-modules

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éspour 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'unprojet 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 queces liens soient correctement résolus. On peut également utiliser le goal site:stage pour

que ces liens fonctionnent en local.








8/8/2019 Maven Site





7 - Ajout de contenu

En plus des pages et des informations directement générés par Maven 2, il est possible d'ajouter des pages decontenu 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 ensuites générées au format HTML par Maven. Le nom du fichier sera le même, seule l'extensionva changer.

Si la page au format .html existe déja lors d e la génération du site, Maven ne va pasregé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 toutesles pages seront regénèrées.

7.1 - Format APT

Ce format permet de décrire des pages web de contenu dans un simple format texte. Le format utilisé est assezproche d'un format wiki et se veut très simple.

Ce formet de fichier fonctionne par niveau d'identation. 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 posssible decréer des sections et sous-sections en utilisant le caractère étoile. Voici donc un exemple de fichier APT avec unecertaine hierarchie 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 :








8/8/2019 Maven Site





Page au format APT

Ces pages respectent le format Maven et donc le skin qui est appliqué au site.







8/8/2019 Maven Site





7.1.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 estpossible de faire :

• Italique : Entourer le texte de < >• Gras : Entourer le texte de << >>• Font monospaced : Entourer le texte de <<< et >>>

Et voici un exemple intégrant ces 3 formattages :

Formatage

Un peu de gras sur <<lui>>. De l'italique sur <moi> et pour finir <<<monsieur>>> utilise une police decaractères monospaced.

Voici le rendu de cet exemple :

Texte formatté

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







8/8/2019 Maven Site





[[1]] Elément numéroté 1

[[A]] Elément numéroté A.

[[B]] Elément numéroté B.

[[2]] Elément numéroté 2

[]

qui aura pour effet de générer la page suivante :

Listes numérotées

7.1.3 - Tableaux

On peut également ajouter des tableaux. Ce format est également aussi intuitif, il consiste en fait à dessinner 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 | | |*-------------------------*----------------+----------------:-----------------:







8/8/2019 Maven Site





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 center la premièrecolonne, 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 dessinner leslignes du tableaux.

7.1.4 - Ancres et liens

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

Premièrement pour définir une ancre, il sufit 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}}

7.1.5 - Divers

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

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







8/8/2019 Maven Site





Il suffit en fait de 3 caractères = pour que cel a 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 ~~.

7.2 - 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 duformat APT, ce format n'utilise pas son propre format de formatage, mais utilise de l'HTML pour le formatage desquestions.

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> 

Pas du tout. Ce n'est qu'un projet exemple.

</answer> </faq> <faq id= "article" > <question> Qui est l'auteur de ce projet ? </question> <answer> 

Baptiste Wicht.

</answer> </faq> </part> <part id= "Article" > <faq id= "article" > <question> Est-ce que l'article est utile ? </question> <answer> 

Oui. Il vous apprendra à créer et à personnaliser un site pour un projet Maven 2.

</answer> </faq> <faq id= "article" > <question> De quoi traite cet article ? </question> <answer> 

Il traite de la génération de site dans Maven 2. </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 :








8/8/2019 Maven Site





FAQ sur le projet







8/8/2019 Maven Site





8 - 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 enregister un ensemble clé/mot de passe dans le fichier settings.xml, pour cela, ilfaut 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 ou 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 d ossier de base dans lequel est généré lesite, c'est pourquoi il faut préalablement s'assurer que le dossier dans lequel le site seragé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 doncvous armer de patience. Dans le cas de ce projet, cela prend environ 1 minutes sur ma connexion à 300 Ko/s d'upload.

Le goal deploy nécessite que le site soit préala blement 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.









8/8/2019 Maven Site





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.



http://baptiste-wicht.developpez.com/tutoriel/java/maven/site/projet/






8/8/2019 Maven Site



9 - 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 sitea 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 ZIPqui contient tous les fichiers nécessaires.

N'hésitez pas à commenter cet article :

9.1 - Remerciements

Un grand merci à Romain Linsolas pour ses relectures !

http://www.developpez.net/forums/u68951/romaintaz/

ftp://ftp-developpez.com/baptiste-wicht/tutoriel/java/maven/site/fichiers/maven-site-pom.zip

Documents

Maven Site