Documentation des modèles

Plugin SPIP permettant de générer automatiquement une documentation technique et fonctionnelle des modèles éditoriaux déclarés sur un site.

Il analyse les modèles disponibles (via leurs fichiers YAML compatibles avec le plugin Insérer Modèles) et produit une fiche détaillée dans l’espace privé.

Objectif

Fournir :

• Une vue structurée des modèles disponibles
• La liste complète de leurs paramètres
• Le détail exhaustif des options déclarées dans les YAML
• Les valeurs possibles (datas)
• Une définition fonctionnelle du type de champ (input, selection, textarea, etc.)
• Une documentation cohérente avec le plugin Saisies

Ce plugin transforme les déclarations techniques en véritable documentation exploitable.

Accès

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

/ecrire/?exec=modeles_doc

Accès réservé aux utilisateurs autorisés à créer des articles.

Fonctionnement

Le plugin :

1. Liste les modèles disponibles
2. Les regroupe par catégories
3. Analyse leurs paramètres déclarés en YAML
4. Affiche pour chaque paramètre :
   • Le libellé
   • Le nom technique
   • Le type de saisie
   • Les options déclarées
   • Les valeurs possibles (datas)
   • Une définition pédagogique du type de champ

Architecture

Le plugin repose sur une structure volontairement simple :

• prive/squelettes/contenu/modeles_doc.html
  Interface principale dans l’espace privé. Elle construit la documentation via des boucles DATA à partir des modèles détectés.
• modeles_doc_fonctions.php
  Contient l’ensemble de la logique métier du plugin :
  • Liste des modèles disponibles
  • Regroupement par catégories
  • Traitement des paramètres
  • Génération des définitions pédagogiques des types de saisie
  • Fonctions utilitaires et filtres éventuels
• lang/
  Chaînes de langue propres au plugin.
• paquet.xml
  Déclaration du plugin et de ses dépendances.

Le plugin privilégie :

• Une logique légère côté PHP
• Un rendu structuré via boucles DATA
• Une séparation claire entre traitement et affichage

Intégration avec Saisies

Les labels d’options sont récupérés via les chaînes de langue du plugin Saisies :

[(#VAL{saisies:option_}|concat{#CLE,'_label'}|_T)]

Cela garantit :

• Cohérence avec l’écosystème SPIP
• Maintenabilité
• Compatibilité évolutive

Définitions pédagogiques

Le plugin ajoute une couche de compréhension fonctionnelle.

Exemples :

Les définitions sont gérées dans la fonction modeles_doc_liste_definition. Les définitions fonctionnelles sont générées dynamiquement à partir du type de saisie (saisie) et de ses options (ex : input + type=text).
Ce mécanisme permet d’enrichir progressivement la documentation sans modifier les modèles YAML.

Affichage

L’interface utilise :

• Boucles DATA
• Structuration .champ > .label + .span
• Flexbox moderne (compatible SPIP 4)
• Styles isolés sous .modeles_doc

Exemple d’affichage

Pour un paramètre :

Disposition horizontale [selection]

Type de champ :
Liste déroulante permettant de choisir une valeur.

Nom du paramètre :_ horizontal

Option intro :
(défaut)

Choix possibles :

• 30
• 50
• oui

Dépendances

• SPIP 4.x
• Plugin Saisies
• Plugin YAML

Le plugin exploite les modèles déclarés via fichiers YAML (compatibles avec le plugin Insérer Modèles).

Roadmap

Fonctionnalités prévues :

• ⚠️ Détection d’incohérences :
  • paramètre structurel mal déclaré
• 🧪 Indication optionnel / obligatoire

Philosophie

Ce plugin vise à :

• Améliorer la qualité documentaire des projets SPIP
• Faciliter la transmission entre développeur.e.s et utilisateurices
• Rendre explicite ce qui est implicite dans les YAML
• Standardiser la gestion des modèles éditoriaux

Auteur

Approche orientée qualité, documentation et structuration des pratiques SPIP.

Licence

GPL compatible SPIP