Télécharger
FAQ
Templeet pas à pas
 |  |
 |
XIV. Ecriture d'une page de documentation.
Chaque module Templeet devrait posseder une page de documentation, que ce soit un module faisant partie de la distribution de base ou bien un module se trouvant dans un package.
Une page de documentation Templeet possède une structure bien particulière qui permet non seulement d'harmoniser les pages entre elles, mais qui en plus rend possible une indexation croisée des fonctions par ordre alphabétique et par module. Par ailleurs la gestion documentaire de Templeet indique les éventuelles fonctions qui ne sont pas traitées dans la documentation.
Cette structure est composée de quatre partie:
- déclaration du contenu de la page
- titre de la page
- index de la page
- description des fonctions
La partie déclaration est la seule qui n'aparaisse pas directement dans la page.
Les informations qui s'y trouvent sont utilisées aussi bien pour construire de manière
automatique la partie index que pour créer la page qui indexe toutes les fonctions
de tous les modules.
Les autres parties apparaissent directement dans la page.
Voici le code correspondant à cette page:
~set('mod_doc[dir]',"gestion de répertoire") ~set('inst[dir]',~array( '#titre' => "<p>Il offre les fonctions suivantes:</p>", 'createdir' => ~array( "createdir","création de répertoires récursivement"), 'compactdir' => ~array( "compactdir","canonisation d'un chemin") ))<div class="tablehuge"> Le module DIR propose 2 fonctions pour la gestion de répertoires. </div>~include('../setaname.tmpl',~get('inst[dir]')) ~include('../listfunc.tmpl') <hr/><a id="createdir"></a> <h1>createdir</h1> La fonction ~createdir() prend un argument, le nom du répertoire à créer. Cette fonction peut créer des répertoires récursivement s'ils n'existent pas. <br/><br/> <i>Note : Cette fonction fait appel à la fonction createdir de templeet.php</i> <br/><br/>Exemple :<br/><br/> <div class="code"> <pre> ~createdir('plop/pika/test/') </pre> </div> <br/>Si les répertoires 'plop', 'pika' n'existent pas, ils sont créés au passage. <div class="top"> <p><a href="#top">Revenir en haut</a></p> </div> <a id="compactdir"></a> <h1>compactdir</h1> La fonction ~compactdir() prend un argument, un chemin à vérifier. Elle retourne le chemin sous forme compacte, en retirant les '.' et '..'. <br/><br/> Cette fonction est utile pour vérifier un argument passé en paramètre et utilisé ensuite au niveau du système de fichiers, pour des questions de sécurité. <br/><br/>Exemple :<br/><br/> <div class="code"> <pre> ~compactdir('/var/www/Templeet/templates/../linuxfr/') </pre> </div> <br/>Cela se transforme en : ~compactdir('/var/www/Templeet/templates/../linuxfr/') <div class="top"> <p><a href="#top">Revenir en haut</a></p> </div>
Déclaration du contenu de la page
~set('mod_doc[nom du module]',"titre du module qui apparait dans la liste des modules")
~set('inst[nom du module]',~array(
'#titre' => "<p>Il offre les fonctions suivantes:</p>",
'nom de la fonction' => ~array( "nom de l'ancre dans la page","titre de la fonction"),
'nom de la fonction' => ~array( "nom de l'ancre dans la page","titre de la fonction")
.
. // à répéter pour chaque fonction
.
))
Titre de la page
<div class="tablehuge">titre de la page</div>
Index de la page
~include('../setaname.tmpl',~get('inst[nom du module]'))
~include('../listfunc.tmpl')
<hr/>
Description des fonctions
Ce bout de code Templeet est à répéter pour chacune des fonctions traitées.<a id="nom de l'ancre"></a> <h1>nom de la fonction</h1> description de la fonction<br/><br/> Les exemples se mettent dans des div comme ceci:<br/><br/> <div class="code"> <pre> exemple bla bla bla </pre> </div> <div class="top"> <p><a href="#top">Revenir en haut</a></p> </div>
Cas particuliers de déclarations de contenu de la page
Certains modules peuvent nécessiter une partie introductive avant l'énumération des fonctions. Dans cette hypothèse il suffit d'ajouter une entrée dans le tableau dont la clef commence par un point. Les pages de documentation core et auth contiennent de tels exemples.
~set('inst[core]',~array(
'#titre' => "<p>Les fonctions disponibles sont les suivantes:</p>",
'.blocs' => "Les <a href=\"#block\">blocs</a> d'instructions",
'.comment' => "<a href=\"#comment\">Les \"vrais\" commentaires</a>",
.
.
.
Il arrive que plusieurs fonctions soient traitées en une seule fois parce que complémentaires par exemple. A nouveau core présente deux exemples avec set et get d'une part et inc et dec d'autre part. Chacune des fonctions est alors déclarée dans le tableau mais en mettant à chaque fois la même ancre:
~set('inst[core]',~array(
'#titre' => "<p>Les fonctions disponibles sont les suivantes:</p>",
'.blocs' => "Les <a href=\"#block\">blocs</a> d'instructions",
'.comment' => "<a href=\"#comment\">Les \"vrais\" commentaires</a>",
'set' => ~array( "setget","définir et récupérer une variable"),
'get' => ~array( "setget","définir et récupérer une variable"),
.
.
.
'inc' => ~array( "incdec","fonctions d'incrémentation et de décrémentation"),
'dec' => ~array( "incdec","fonctions d'incrémentation et de décrémentation"),
.
.
.
Au niveau de l'index des fonctions, elles sont alors regroupées en une seule ligne:
Il se peut que des fonctions soient intimement liées comme les fonctions de liste par exemple. On peut alors ne faire qu'une seul entrée de liste mais avec des liens différents pour chaque fonction. authedit présente plusieurs exemples de ce type. En mettant un point d'exclamation au début de la clef le gestionnaire de documentation ne créera pas une entrée de liste pour la fonction suivante:
. . . '!auth_listuser' => ~array( "auth_listuser","lister les comptes utilisateurs de Templeet"), '!auth_listuserfld' => ~array( "auth_listuserfld","renvoie une propriété d'un compte utilisateur listé par la fonction auth_listuser"), 'auth_nbrows' => ~array( "auth_nbrows","renvoie le nombre de comptes utilisateur sélectionnés par la fonction auth_listuser"), . . .
Ce qui donne:
Un module comme authedit qui contient beaucoup de fonctions doit les regrouper en familles. Ainsi dans cet exemple on peut trouver des fonctions de manipulation d'utilisateurs, de manipulation de zones et de validation de comptes. Dans l'index chacune de ces familles apparait avec un titre dans la liste des fonctions. Pour ajouter un titre il suffit d'ajouter un élément de tableau dont la clef commence par #. Ce qui suit n'a pas d'importance mais toutes les clefs du tableau doivent être différentes. Le titre se trouve dans la valeur de l'élément.
~set('inst[authedit]',~array(
'#titre1' => "<p>Fonction de manipulation d'utilisateur :</p>",
'auth_newuser' => ~array( "auth_newuser","créer un nouvel utilisateur"),
'auth_deluser' => ~array( "auth_deluser","supprime un utilisateur"),
'auth_setprivuser' => ~array( "auth_setprivuser","définit le niveau de privilège d'un utilisateur sur une ou plusieurs zones"),
'!auth_listuser' => ~array( "auth_listuser","lister les comptes utilisateurs de Templeet"),
'!auth_listuserfld' => ~array( "auth_listuserfld","renvoie une propriété d'un compte utilisateur listé par la fonction auth_listuser"),
'auth_nbrows' => ~array( "auth_nbrows","renvoie le nombre de comptes utilisateur sélectionnés par la fonction auth_listuser"),
'!authlist' => ~array( "authlist","lister les propriétés d'un compte"),
'authfld' => ~array( "authfld","renvoie la valeur d'une propriété d'un compte listé par la fonction authlist"),
'auth_passwd' => ~array( "auth_passwd","modifie le mot de passe d'un utilisateur"),
'auth_loginnick' => ~array( "auth_loginnick","modifie l'identifiant de connexion (<em>login</em>) et le pseudo
(<em>nickname</em>) d'un utilisateur</li>"),
'auth_newmail' => ~array( "auth_newmail","demande de modification d'adresse électronique d'un utilisateur"),
'auth_setnewmail' => ~array( "auth_setnewmail","validation de la demande de modification de l'adresse électronique d'un utilisateur"),
'#titre2' => "<p>Fonction de manipulation des zones :</p>",
'auth_newarea' => ~array( "auth_newarea","création d'une nouvelle zone"),
'auth_delarea' => ~array( "auth_delarea","suppression d'une zone"),
'auth_setarea' => ~array( "auth_setarea","modification du champ label d'une zone"),
'!auth_listarea' => ~array( "auth_listarea","lister les zones existantes"),
'auth_listareafld' => ~array( "auth_listareafld","renvoie la valeur d'une propriété d'une zone listé par la fonction auth_listarea"),
'#titre3' => "<p>Fonction de gestion de validation des comptes :</p>",
'auth_validmode' => ~array( "auth_validmode","renvoie le mode de validation courant"),
'auth_validaccount' => ~array( "auth_validaccount","valide un compte précédemment créé"),
'auth_setconfvalid' => ~array( "auth_setconfvalid","modifie le mode de validation courant des comptes")
))
| |
|