Lutece : guide développeur
Les règles de documentation
La documentation de Lutèce est écrite au format XML, puis est générée à l'aide de Maven aux formats HTML et PDF à l'aide de la commande :
$ mvn site
Un nombre limité de balises est utilisé, afin de permettre une mise en page homogène dans les deux formats.
Créer une documentation : les règles de base
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 moins 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> :
Attention : pour que le rendu soit conforme lors de l'utilisation de la balise <pre> , il faut coller le texte à gauche, sans tenir compte de l'indentation générale du code xml du fichier.
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.
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.
Le résultat est :
Documentation Markdown pour GitHub
Un plugin Maven spécifique à Lutece permet de convertir la page d'accueil de la documentation au format xDoc (fichier index.xml en anglais) en un fichier README.md au format Markdown utilisé par GitHub.
Voici la commande :
$ mvn fr.paris.lutece.tools:xdoc2md-maven-plugin:readme