Normes de documentation
La documentation des plugins Lutèce dot être écrite au format xDoc (XML), puis est générée à l'aide de Maven aux formats HTML et PDF.
Documentation du plugin Maven xdoc2md.
La documentation doit contenir au minimum un fichier site et index en français et en anglais.
Voici l’arborescence minimale de la documentation :
Structuration du Xdoc
Le XDOC doit être obligatoirement structuré avec les sections suivantes :
- nom du plugin
- mots clés : les mots clés définissant les champs d'utilisation du plugin. Il permettront la classification du plugin et seront utilisés comme mots clés de recherche. Ces mots clés doivent être dans la langue du XDOC. Exemples : "cms, authentication, cms, workflow, seo, collaborative, ..." .
- Introduction : la description générale de l'objectif et des fonctionnalités fournies par le plugin
- Configuration : les différentes options à configurer pour l'utilisation du plugin dans les fichiers properties, xml ...
- Usage : Le mode d'emploi des services du plugin. Cette section peut contenir des exemples de code Java ou des copies écran pour l'utilisation des fonctionnalités.
Modèle de XDOC :
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Plugin {NOM_DU_PLUGIN}</title>
</properties>
<head>
<meta name="keywords" content="{MOT_CLE_A},{MOT_CLE_B},{MOT_CLE_C}"/>
</head>
<body>
<section name="Plugin {NOM_DU_PLUGIN}">
<subsection name="Introduction">
<p>...</p>
</subsection>
<subsection name="Configuration">
<p>...</p>
</subsection>
<subsection name="Usage">
<p>...</p>
</subsection>
</section>
</body>
</document>
Créer une documentation : les règles générales
Un nombre limité de balises est utilisé, afin de permettre une mise en page homogène dans les deux formats.
L'encoding utilisé est UTF-8, les chapitres sont découpés en section et subsection .
Le code HTML inclu dans ces chapitres ne doit pas utiliser la balise <br> , mal interpretée lors de la génération PDF. La balise <p> est donc à utiliser pour effectuer des retours à la ligne.
Les tables doivent comporter au mmoins un titre en première ligne( <th> )
Les images doivent mesurer 780px de large (centrer l'image sur fond blanc), et être créées au format .gif .
Exemples de mise en oeuvre des balises
Un document peut contenir plusieurs sections.
Une section peut contenir du texte formaté par un paragraphe (<p> ), ainsi qu'une ou plusieurs sous-section(s)
Exemple :
<section name=Titre de chapitre 1>
<p>
Introduction du chapitre 1
</p>
<subsection name=Sous-chapitre 1>
<p>
texte ...
</p>
</subsection>
<subsection name=Sous-chapitre 2>
<p>
texte ...
</p>
</subsection>
</section>Le résultat est le suivant :
Titre de chapitre 1
Introduction du chapitre 1
Sous-chapitre 1
texte ...
Sous-chapitre 2
texte ...
Il est possible d'inclure une liste dans un paragraphe :
<p>
<ul>
<li>exemple de liste 1</li>
<li>exemple de liste 2</li>
</ul>
</p>
<p>
<ol>
<li>exemple de liste numérotée 1</li>
<li>exemple de liste numérotée 2</li>
</ol>
</p>Résultat :
- exemple de liste 1
- exemple de liste 2
- exemple de liste numérotée 1
- exemple de liste numérotée 2
Le texte peut être formaté avec des balise du type <strong> , <em> , <code>
<p>
<code>texte au format code</code>
</p>
<p>
<strong>texte au format strong</strong>
</p>
<p>
<em>texte au format em</em>
</p>
Résultat :
- texte au format code
- texte au format strong
- texte au format em
Des exemples de code peuvent être introduit à l'aide de la balise <pre> :
<p> <div class=source> <pre> <application> <application-class>fr.paris.lutece.plugins.securedtest.SecuredTestApp</application-class> <application-security-model>1</application-security-model> </application> </pre> </div> </p>
Le résultat est :
<application>
<application-class>fr.paris.lutece.plugins.securedtest.SecuredTestApp</application-class>
<application-security-model>1</application-security-model>
</application>Pour insérer un tableau, la syntaxe est la suivante :
<p>
<table>
<tr>
<th>Titre 1</th>
<th>Titre 2</th>
</tr>
<tr>
<td>Colonne 1</td>
<td>Colonne 2</td>
</tr>
</table>
</p>Ce qui donne le tableau suivant :
| Titre 1 | Titre 2 |
|---|---|
| Colonne 1 | Colonne 2 |
Pour afficher une copie d'écran :
<p>
<center>
<img src=images/logo_lutece.gif />
</center>
</p>La balise <center> n'est prise en compte que pour la génération HTML.
Pour que l'image ne soit pas déformée dans la version PDF, une astuce consiste à créer l'image utilisée pour la génération de ce format sur une taille de 780px de large (pour un format de sortie A4), la copie d'écran étant centrée dans cette largeur.