Utilisation du plugin maven-siteAuteur : Julien Gauchet le 21/11/2017 (1 revision)

Cette page permet de résumer en quelques étapes une façon de créer un maven-site. La documentation complète est disponnible ici : Documentation maven site

1. Installation

L'utilisation du plugin maven-site est à déclarer dans le fichier pom.xml du projet contenant la documentation. Vous pouvez Consulter la documentation sur la page suivante : plugin maven site

Pour pouvoir utiliser le plugin maven-site, il faut ajouter le plugin dans le fichier pom.xml. Je vous propose d'ajouter également :

  • Une dépendance à wagon-ssh qui permettra de déployer le site via une connexion sécurisée ssh
  • Le plugin project-info-reports permettant de générer automatiquement de la documentation pour le maven site

Nous aurons alors le pom.xml suivant. Notez qu'il sera intéressant de définir les balises permettant de nommer et de décrire le projet, les développeurs afin que le plugin maven-site les utilise.

<project>
	...
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-site-plugin</artifactId>
				<version>3.5.1</version>
				<dependencies>
					<dependency>
						<groupId>org.apache.maven.wagon</groupId>
						<artifactId>wagon-ssh</artifactId>
						<version>1.0</version>
					</dependency>
				</dependencies>
			</plugin>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-project-info-reports-plugin</artifactId>
				<version>2.9</version>
			</plugin>
		</plugins>
	</build>
</project>

Il faudra ensuite définir, toujours dans le fichier pom.xml l'adresse à laquelle on souhaite déposer le site maven

<project>
	...
	<distributionManagement>
		<site>
			<id>gforge.insee.fr</id>
			<name>GForge</name>
			<url>scp://gforge.insee.fr/var/lib/gforge/chroot/home/groups/[projet]/htdocs</url>
		</site>
	</distributionManagement>
</project>

2. Initialiser son site

L'initialisation du site consiste à créer l'arborescence de celui-ci ainsi qu'à définir le contenu à générer dans le fichier site.xml

2.1. Arborescence à créer

Pour des explications complètes sur les dossiers à créer et pour connaitre toutes les possibilités offertes par maven-site, reportez-vous à la documentation suivante : Structure des dossiers

Pour initialiser le site, il faut créer le dossier src/site ainsi que l'arborescence suivante :

  • src/site
    • apt : Dossier qui contiendra les pages à publier au format Doxia (langage wiki)
    • puml : Dossier contenant les diagrammes plantuml (si cet outil est utilisé)
    • resources : Dossier contenant les resources accessibles via le site de documentation
      • css : Dossier contenant les feuilles de style
        • site.css : Le nom de la css est obligatoirement site.css
      • images : Dossier dans lequel nous allons déposer les images
    • site.xml : Fichier de configuration du site

Un exemple de css est téléchargeable ici : Css de tourisme3

2.2. Fichier site.xml

Le contenu du fichier site.xml permet de définir les éléments à générer ainsi que le menu du site. Pour connaitre l'ensemble des possibilités offertes, reportez-vous à la documentation suivante : Configuration du descripteur de site

Ci-dessous un exemple de fichier site.xml

<?xml version="1.0" encoding="UTF-8"?>
<project name="Tourisme3" xmlns="http://maven.apache.org/DECORATION/1.7.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0 http://maven.apache.org/xsd/decoration-1.7.0.xsd">
	<skin>
		<groupId>org.apache.maven.skins</groupId>
		<artifactId>maven-fluido-skin</artifactId>
		<version>1.6</version>
	</skin>

	<body>
		<menu name="Apercu" inherit="top">
			<item name="Accueil" href="index.html" />
		</menu>
		<menu name="Documentation fonctionnelle" inherit="top">
			<item name="Dictionnaire des données" href="dictionnaire-donnees/index.html" />
			<item name="Lancement des batch en recette" href="lancement-batch-recette.html" />
			<item name="Glossaire" href="glossaire.html" />
		</menu>
		<menu name="Pilotage" inherit="top">
			<item name="Suivi des versions" href="suivi/index.html" />
		</menu>
		
		 <footer><![CDATA[
		 	<a href='#'>Haut de page</a>
		 ]]></footer>
	</body>
</project>

3. Définir du contenu

Le contenu du site de définit grâce au langage Doxia. Les fichiers sont créés dans le dossier apt

3.1. Un éditeur Doxia pour éclipse

L'éditeur Doxia bien qu'un peu vilain permet de valider la structure de nos pages doxia ainsi que de fournir un aperçu du rendu. La documentation est ici : Site doxia

Pour l'installer, suivez les étapes suivantes :

  • Dans Eclipse : Help > Install New Software > Add...
  • Name : par exemple "doxia"
  • Location : http://maven.apache.org/doxia/doxia-ide/eclipse/eclipse/.
  • Cocher la bonne proposition dans le champ en dessous > Next ... sélectionner les lignes affichées (cliquer dessus) > Finish.

3.2. Le format apt

Pour créer une page sur le site, il faut créer un fichier page.apt et définir le contenu grâce au langage doxia décrit ici : Langage doxia apt

Ci-dessous un exemple de page :

Table communes


* Description

  Table contenant les communes utilisées dans l'application.     

  Ces communes sont issues du Code Officiel Géographique (COG).

* Structure

** Les colonnes de la table

  Le tableau ci dessous présente les différentes colonnes de la table.

*-----+---+--------+
|| Nom   || Type   || Description   
*-----+---+--------+
| <<numero>>   | <<int>>   | <<Numéro de commune dans le COG>>   
*-----+---+--------+
| numero_departement (reference {{{./departements.html}departements}})   | int   | Numéro de département de la commune   
*-----+---+--------+
| numero_region (reference {{{./regions.html}regions}})   | int   | Numéro de région de la commune   
*-----+---+--------+
| nom_commune   | text   | Nom de la commune   
*-----+---+--------+

** Contraintes

  * La colonne <<numero>> est la clé primaire de la table (unique, et non nulle)

  * La colonne <<numero_departement>> ne doit pas être nulle

  * La colonne <<numero_region>> ne doit pas être nulle

  * La colonne <<numero_departement>> est une référence vers la table departements

  * La colonne <<numero_region>> est une référence vers la table regions

  * La colonne <<id_aire_touristique>> est une référence vers la table aires_touristiques

[]

* Dépendances

  Le diagramme suivant montre les tables dont dépend le table communes

[../images/classes-dependences/communes.png]

* Accéder et manipuler les données de la table

  <<Sélection des données>>

----
  SELECT numero, numero_departement, numero_region, nom_commune, id_aire_touristique, commune_supprimee FROM communes
----
  <<Insertion d'une ligne>>

----
  INSERT INTO communes(numero, numero_departement, numero_region, nom_commune, id_aire_touristique, commune_supprimee) 
  VALUES (?, ?, ?, ?, ?, ?)
----

4. Générer et déployer le site

Pour générer le site en local (il sera créé dans le dossier targer du projet), lancer mvn site:site sur le projet contenant le site.

Une fois cette première étape effectuée, pour déployer le site sur le dépot précisé dans la base distributionManagement, lancer un mvn site:deploy

La liste complète des goals maven est disponnible ici : Goals maven