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 :
Créer une documentation : les règles de base
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
Structure globale du fichier :
<?xml version=1.0 encoding=UTF-8?>
<document>
<properties>
<title>Lutèce : titre du document</title>
</properties>
<body>
<section name=Titre de chapitre 1>
...................
</section>
</body>
</document>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.