Documentation des modèles

Le plugin Documentation des modèles permet de générer automatiquement une documentation des modèles éditoriaux disponibles sur un site SPIP.

Il s’appuie sur les fichiers YAML des modèles, utilisés notamment par le plugin Insérer Modèles, pour produire une page de documentation dans l’espace privé.

Cette documentation est destinée à la fois :

• aux rédacteurs et rédactrices ;
• aux webmestres ;
• aux intégrateurs ;
• aux développeurs et développeuses ;
• aux équipes projet qui doivent comprendre les modèles disponibles sur un site.

Objectif

Le plugin transforme les déclarations techniques des modèles en une documentation lisible et exploitable.

Il permet notamment de connaître :

• les modèles disponibles sur le site ;
• leur catégorie ;
• leur description ;
• leur exemple d’utilisation ;
• leurs paramètres configurables ;
• les paramètres obligatoires ;
• les paramètres cachés ;
• les valeurs possibles ;
• les vérifications déclarées ;
• les éventuelles incohérences détectées.

Accès

La page de documentation est accessible dans l’espace privé :

/ecrire/?exec=modeles_doc

L’accès est réservé aux personnes autorisées à créer des articles.

Fonctionnement général

Le plugin :

1. recherche les fichiers YAML présents dans le répertoire modeles/ ;
2. vérifie qu’un fichier HTML de modèle correspondant existe ;
3. charge les informations déclarées dans le YAML ;
4. regroupe les modèles par catégories ;
5. analyse les paramètres déclarés ;
6. génère un exemple d’utilisation ;
7. affiche une fiche complète pour chaque modèle.

Exemple d’utilisation généré

Pour chaque modèle, le plugin génère automatiquement un exemple de syntaxe SPIP.

Exemple :

<album|nivoslider|id_album=1>

L’exemple est construit à partir des informations déclarées dans le fichier YAML.

Le plugin prend notamment en compte :

• le paramètre modele, lorsqu’il est présent ;
• le paramètre variante, lorsqu’il est présent ;
• les paramètres obligatoires ;
• les paramètres cachés ;
• les saisies spécifiques de type param_modele.

Les paramètres modele et variante ne sont pas réaffichés sous forme modele=... ou variante=... lorsqu’ils servent à construire la syntaxe principale du modèle.

Ainsi, un modèle déclaré avec :

modele = album
variante = nivoslider
id_album = 1

sera documenté sous la forme :

<album|nivoslider|id_album=1>

plutôt que :

<album_nivoslider|modele=album|variante=nivoslider|id_album=1>

Paramètres documentés

Pour chaque paramètre, le plugin affiche :

• le libellé ;
• le nom technique ;
• le type de saisie ;
• une définition lisible du type de champ ;
• les options déclarées ;
• la valeur par défaut, lorsqu’elle existe ;
• les valeurs possibles, lorsqu’elles sont déclarées ;
• les vérifications éventuelles ;
• les incohérences détectées.

Badges

Le plugin ajoute des badges permettant d’identifier rapidement la nature des paramètres.

Les principaux badges sont :

• Champ visible ;
• Champ caché ;
• Obligatoire ;
• Paramètre structurel ;
• Incohérent.

Ces badges permettent de distinguer rapidement les paramètres utiles aux rédacteurs des paramètres plus techniques nécessaires au fonctionnement du modèle.

Détection d’incohérences

Le plugin signale certaines incohérences simples dans les déclarations YAML.

Par exemple :

• une saisie de type selection, radio ou checkboxes sans liste de valeurs ;
• certains paramètres incomplets ou ambigus.

Ces alertes permettent d’améliorer progressivement la qualité des modèles déclarés sur le site.

Catégories

Les modèles sont regroupés par catégories afin de faciliter leur consultation.

Le plugin réutilise les catégories déclarées par les modèles, conformément aux conventions du plugin Insérer Modèles. Lorsqu’aucune catégorie n’est déclarée, ou lorsqu’une catégorie inconnue est rencontrée, le modèle est automatiquement reclassé dans la catégorie Divers.

Les catégories peuvent être enrichies via le pipeline :

modeles_lister_categories

Ce qui donne cette liste de catégories par défaut :

• champ libre ;
• choix restreint ;
• structure ;
• contenu éditorial ;
• divers.

Pipelines

Le plugin propose deux pipelines.

modeles_lister_disponibles

Permet de modifier la liste des modèles détectés.

function monplugin_modeles_lister_disponibles(array $modeles): array {
	return $modeles;
}

modeles_lister_categories

Permet d’ajouter ou modifier les catégories de classement.

function monplugin_modeles_lister_categories(array $categories): array {
	$categories['ma_categorie'] = [
		'nom' => 'Ma catégorie',
	];

	return $categories;
}

Interface privée

L’interface utilise le layout privé :

#LAYOUT_PRIVE{complements-gauche}

La navigation par catégories et modèles est placée dans la colonne gauche.

Chaque fiche modèle affiche :

• le titre et la description du modèle ;
• un résumé discret du nombre de paramètres et des éventuelles alertes ;
• un exemple d’utilisation mis en évidence ;
• les paramètres présentés sous forme de fiches lisibles ;
• les explications, libellés de cases, indications de saisie, valeurs par défaut et choix possibles utiles à la rédaction ;
• les contraintes de saisie et les états particuliers sous une forme compréhensible ;
• les informations techniques et les vérifications dans des volets repliables.

Cette présentation progressive privilégie les informations utiles aux rédacteurs et rédactrices. Les détails nécessaires aux webmestres et aux équipes techniques restent accessibles sans alourdir la lecture courante.

Chaînes de langue complémentaires

Le plugin complète certaines chaînes de langue utilisées par des plugins tiers afin d’améliorer l’affichage de la documentation.

Des compléments sont fournis pour certains libellés issus notamment de :

• Saisies ;
• Vérifier ;
• GIS ;
• Albums ;
• Insérer Modèles ;
• Modèle Médias.

Ces compléments permettent d’éviter l’affichage de chaînes techniques non traduites dans la documentation.

Dépendances

Le plugin nécessite :

• SPIP 4.2 ou supérieur ;
• Saisies ;
• YAML ;
• Vérifier.

Structure du plugin

Principaux fichiers :

• modeles_doc_fonctions.php Contient la logique de détection, de chargement, d’analyse et de génération des exemples.

• prive/squelettes/contenu/modeles_doc.html Page principale de documentation dans l’espace privé.

• prive/squelettes/inclure/modeles_doc_info.html Affichage d’une fiche modèle.

• prive/squelettes/inclure/modeles_doc_info_parametres.html Affichage détaillé des paramètres d’un modèle.

• prive/squelettes/navigation/modeles_doc.html Navigation latérale par catégories et modèles.

• prive/style_prive_plugin_modeles_doc.html Styles dédiés à l’interface privée du plugin.

• lang/ Chaînes de langue du plugin et compléments nécessaires à l’affichage.

Philosophie

Le plugin vise à produire une documentation vivante des modèles installés sur un site SPIP.

L’objectif est de limiter la documentation manuelle, souvent difficile à maintenir, en s’appuyant directement sur les fichiers YAML utilisés par les modèles.

La documentation reste ainsi alignée avec les modèles réellement disponibles sur le site.

Licence

GPL compatible SPIP.