Aide:Documentation des modèles
 |
En résumé : La documentation d'un modèle se fait dans une sous-page « /documentation ».Il faut insérer à la fin de la page du modèle le code suivant : « <noinclude>{{Documentation}}</noinclude> ».La documentation doit suivre une structure clair :
|
Généralités modifier
Chaque modèle doit être documenté et être lié à sa page de documentation. S'il n'y a pas de documentation, il faudra impérativement placer dans la sous-page de documentation le modèle {{sansdoc}}.
Sous-page de documentation modifier
Il est recommandé de mettre la documentation dans une sous-page dédiée.
Le nom de la page de documentation est composée de : « Modèle:nom-du-modèle » suivi de « /documentation », la barre oblique représente une sous-page.
- Exemple : Modèle:Alinéa/documentation.
Le contenu de la page de modèle peut être contenu entre les balises <includeonly>...</includeonly>, la documentation s'insère à la fin de la page du modèle avec le code suivant : <noinclude>{{Documentation}}</noinclude>.
- Exemple : Modèle:Alinéa).
Catégorisation des modèles modifier
La catégorisation d'un modèle se fait dans la sous-page de documentation « Modèle:nom-du-modèle/documentation » (exemple : Modèle:séparateur/documentation). Cela permet un allègement de la charge des serveurs, une gestion de la protection des modèles plus facile.
- Exemple de catégorisation situé dans la sous-page Modèle:Séparateur/documentation :
<includeonly>
[[Catégorie:Modèles de séparateur|{{PAGENAME}}]]
</includeonly>
<noinclude>
[[Catégorie:Documentations]]
</noinclude>
La catégorie entre les balises <includeonly>...</includeonly> sert à catégoriser le modèle en soit (catégoriser Modèle:Séparateur dans notre cas). La catégorie entre les balises <noinclude>...</noinclude> sert à catégoriser la sous-page de documentation sans catégoriser le modèle (voir aussi l'aide de wikipédia sur le sujet).
Documentation manquante modifier
Si vous tombez sur un modèle non documenté ou insuffisamment, merci d’ajouter le modèle {{Sansdoc}} dans la sous-page de documentation. Cela permet aux contributeurs souhaitant travailler sur la documentation de modèle de retrouver plus facilement les modèles à documenter.
Pourquoi une sous-page modifier
La recommandation d'utiliser une sous-page pour la documentation s'appuie sur plusieurs éléments :
- permettre la protection des modèles sans empêcher la modification de la documentation
- éviter d'avoir un mélange des historiques concernant le modèle et la documentation
- gestion uniforme et simplifiée des pages de documentation.
Structure modifier
Section « Utilisation » et sous-section « Remarques » modifier
La Section « Utilisation » permet de répondre à la question : « à quoi sert le modèle ? » (pour que le contributeur identifie s'il doit l'utiliser pour son problème).
Cette section peut commencer par « Permet de… » pour expliquer à quoi il sert.
La sous-section « Remarques » est quand à elle plus rare, elle permet de décrire des modèles avec plusieurs fonctions (exemple : {{Lang}}, {{Modernisation}}).
Cette sous-section « Remarques » permet de mettre en avant certaines problématiques sur l'utilisation du modèle ou des commentaires (exemple : {{Symbole manquant}}).
Section « Syntaxe » modifier
La section « Syntaxe » sert à afficher un code facilement copiable.
La plupart du temps, la section syntaxe n'a pas de sous-section, le code complet du modèle étant souvent simple, il ne nécessite pas de découpage particulier.
Pour des modèles n'utilisant pas toujours tous les paramètres, il pertinent de proposer deux sous-sections « Syntaxe simplifiée » et « Syntaxe complète ».
- la première « Syntaxe simplifiée » servant d'utilisation de base du modèle (maximum 2-3 paramètres)
- la seconde « Syntaxe complète » servant à proposer tous les paramètres (de manière exhaustive)
Section « Paramètres » modifier
La section « Paramètres » permet de décrire tous les paramètres d'un modèle. Il est renseigné en remplissant le TemplateData. Si vous savez pas utiliser TemplateData il est possible de renseigner les paramètres sans cela en les décrivant un par un
Par ailleurs, le TemplateData s'insère même s'il n'y a pas de paramètre, le but est de signaler qu'il n'y a pas de paramètre (exemple : {{Titre sous-page}}).
Section « Exemple » modifier
Pour la section « Exemple », l'objectif est :
- de montrer ce que fait visuellement le modèle
- de montrer comment fonctionne le modèle
- permettre de commenter un cas complexe d'usage du modèle
La section exemple est mis en forme avec le modèle {{Code rendu}}. Ce modèle me permet de facilement présenter le code à gauche et son résultat à droite.
- Exemple :
{{Code rendu}}
|-
| <pre><nowiki>{{en}}</nowiki></pre> || <div class="pagetext" style="margin:0.5em 0; margin-left:2em; background:#FFF; color:#000; border:1px solid #AAA; padding:2px .5em">{{en}}</div>
|}
Pour l'affichage du rendu (à droite), après les deux pipe « || », le code <div class="pagetext" style="margin:0.5em 0; margin-left:2em; background:#FFF; color:#000; border:1px solid #AAA; padding:2px .5em">…</div> permet de simuler le comportement de l'espace page. Il pertinent de ne pas utiliser ce code (notamment, avec la class="pagetext") lorsque le modèle ne s'utilise pas dans l'espace page ou s'il ne réagit pas différemment (exemple : {{ChapitreNav}}, {{1o}}).
Section « Voir aussi » modifier
La section « Voir aussi » présente les modèles susceptibles d'intéresser le contributeur, de l'aider à trouver le modèle qui répond le mieux à son besoin. Cette section sert aussi à renvoyer vers d'autres pages pertinentes, comme une page d'aide.
Pour faire une lien rapide vers d'autres modèles il faut utiliser le modèle {{m}}.
Squelette du code de la page de documentation modifier
__NOTOC__
== Utilisation ==
=== Remarques ===
== Syntaxe ==
<code><nowiki></nowiki></code>
=== Syntaxe simplifiée ===
<code><nowiki></nowiki></code>
=== Syntaxe complète ===
<code><nowiki></nowiki></code>
== Paramètres ==
== Exemple ==
{{Code rendu}}
|-
| <pre><nowiki>{{en}}</nowiki></pre> || <div class="pagetext" style="margin:0.5em 0; margin-left:2em; background:#FFF; color:#000; border:1px solid #AAA; padding:2px .5em">{{en}}</div>
|}
{{Code rendu}}
|-
| <pre><nowiki>{{en}}</nowiki></pre> || <div class="pagetext" style="margin:0.5em 0; margin-left:2em; background:#FFF; color:#000; border:1px solid #AAA; padding:2px .5em">{{en}}</div>
|}
== Voir aussi ==
* {{m|}}
<includeonly>
[[Catégorie:catégoriedumodèle]]
</includeonly>
<noinclude>
[[Catégorie:catégoriedeladocumentation]]
</noinclude>
Exemples de modèles bien documentés modifier
{{Centré}}{{Séparateur}}{{Droite}}