Aide:Documentation des modèles

Niveau avancé
Nous vous recommandons de lire auparavant Aide:Modèles
Cette page d'aide explique comment documenter un modèle.
Aide : Manuel de Wikisource
En résumé 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 :
  • Utilisation : À quoi sert le modèle
  • Syntaxe : code à copier pour utiliser le modèle
  • Paramètre : liste des paramètres et TemplateData
  • Exemple : différents exemples d'utilisation du modèle
  • Voir aussi : liste de page susceptible d'intéresser le contributeur

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.

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>.

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.

<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
  Voir aussi : TemplateData

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

Voir aussi

modifier