Aide:La structure de la documentation des modèles

La bibliothèque libre.
Aller à : navigation, rechercher

Généralités[modifier]

Pour permettre un allègement des serveurs, une protection des modèles, la documentation des modèles sera séparée du code du modèle lui-même.

Chaque modèle documenté devrait être lié à sa page de documentation ainsi :

  • Le nom de la page du modèle est formé de « Modèle: » suivi du nom du modèle.
  • Le nom de la page de documentation est composé du nom du modèle suffixé par /documentation (la barre oblique est nécessaire et représente une sous-page). Cette page placera la documentation sur un fond vert clair. Ainsi les exemples seront très facilement réaliser pour leur mise point.
    • Exemple pour le modèle {{Alinéa}} : Modèle:Alinéa et Modèle:Alinéa/documentation.

Le contenu de la page de modèle devra commencer par <includeonly> et se finir par :

</includeonly><noinclude>{{Documentation}}</noinclude>
Remarques
  • Parfois des retours de ligne entre ces balises peuvent poser problème.
  • Le code contenu entre les balises <includeonly></includeonly> ne sera pas affiché au-dessus de l’a-plat vert clair de la documentation.


Structure[modifier]

Quant au contenu de la documentation, la structure interne de la documentation commence à se généraliser par mes soins pour permettre une lisibilité homogène sous la forme suivante :

  • Raccourci éventuel du modèle : {{Raccourci|<nowiki>{{modèle}}</nowiki>|nolien=1}}modèle représente le raccourci.
  • Description : décrit les actions et les utilisations du modèle en omettant le plus souvent possible le codage wiki ou HTML.
    • Il sera ajouté au fur et à mesure les balises <section begin=description /><section end=description /> qui permettront de récupérer le texte de cette rubrique de description en vue d’un affichage globale avec tous les autres modèles (voir l'ébauche de la Liste des modèles (en chantier). Ce qui permettra d'avoir une documentation toujours à jour concernant le résumé du descriptif d'un modèle. Cf. {{descriptif}}.
  • Syntaxe(s) : affiche les accolades et le contenu du modèle. Décrit les arguments (le terme paramètre a été retiré, n’étant pas spécifique à l’informatique au contraire d’argument) nécessaires et leurs fonctions. Le caractère obligatoire ou non de la fonction (termes en petites capitales : obligatoire ou optionnel).
Sa syntaxe sera « :<tt><nowiki>{{le-modèle|argument-un|argument-deux…}}</tt> » suivi au dessous de Arguments : et leur description listés par des puces bleues. Chaque argument, chaque valeur sera encadré de la fonction HTML <tt></tt>. La valeur par défaut et les unités utilisées seront présentes si c’est pertinent.
  • Exemple(s) : affiche entre deux balises <pre></pre> le contenu qui sera affiché au-dessous.
On démarrera généralement avec une mise en page sur le côté gauche à l’aide des balises <div class='pagetext'></div> qui encadreront tous les exemples.
  • Voir aussi : liste de liens ou de modèles (listés sous forme de puces bleues) qui pourraient s’avérer utile.
  • puis la liste des catégories :
<noinclude>[[Catégorie:Documentations]]</noinclude>
<includeonly>[[Catégorie:une catégorie]]
[[Catégorie:Modèles documentés]]</includeonly>

Remarque : Lorsque la documentation est très longue, on pourra remplacer le point-virgule au profit du signe égal pour présenter les rubriques.

Remarques[modifier]

  • À la fin de la documentation, entre les balises <includeonly></includeonly> (où se trouvent déjà les catégories francophones), on essaiera de mettre les Templates (modèles) étrangers ! ([[en:Template:a-template]]) en n’en plaçant qu’un par ligne.
  • Parfois, il y aura une rubrique Remarque(s) ou une autre clairement affichée.
  • Lorsqu’aucune documentation n’est réalisée, il faudra impérativement placer dans la documentation le modèle {{sansdoc}}.
  • On prendra soin d’espacer ces rubriques par trois retours de paragraphe, permettant ainsi de rendre la documentation plus aérée. Pour faire une petite marge, chaque paragraphe en romain (en non gras) commencera par un deux-points.


Voir aussi[modifier]