Salut à tous,

Content de voir des réactions sur ce sujet.

Gildas… Hum… Le lien que j’ai envoyé est le code source de la page consultable 
dans le BO. Oui, ceux sont des boucles SPIP. Ces boucles lisent les fichiers 
yaml du plugin Saisies (cf. /ecrire/?exec=saisies_doc). Et oui, pour consulter 
cette page, il faut avoir le plugin YAML installé. Mais c’est la même chose si 
on veut exploiter les fichiers YAML mis à disposition par le plugin Saisies. 
J’ai créé une fonction php qui va chercher les fichier yaml dans les 
répertoires saisies. (Pour vérifier, une fonction va cherche les fichiers yaml 
dans le répertoire verifier/)

Pour beaucoup de ce que je lis c’est une documentation « développeur » et là… 
Je ne suis pas d’accord. Oui, de base les saisies sont utilisés pour générer 
des formulaires… Ah tiens… Formulaires ? Formidable ?

Le plugin Formidable utilise toutes les saisies ayant un fichier html/yaml. De 
ce fait, cette page /ecrire/?exec=saisies_doc n’est pas destinée qu’aux 
développeurs mais également aux personnes créant des formulaires depuis 
l’espace privé de SPIP.

J’ai eu des clients qui ont eu besoin de cette page de documentation. Quand je 
parle de documentation, je ne parle pas d’un article sur SPIP-Contrib ou autre. 
Mais plus d’une page accessible depuis l’espace privé. Elle est présente pour 
des rédacteurs confirmés, voir des administrateurs. Je ne vois pas pourquoi les 
informations données par le fichier YAML pour générer une saisie (cf. 
Formidable) sont plus compréhensibles sous cette forme (à onglet entre autres) 
au lieu d’un texte « au kilomètre ». Ceux sont les même données, affichées 
différemment.

JLuc, non le but n’est pas de rendre obligatoire mais d’offrir une interface 
qui aide l’utilisateur. Il faut maintenant « normer » cela pour que cela soit 
plus simple pour tout le monde.

J’ai parlé du plugin Insérer Modèles car c’est le seul plugin à ma connaissance 
centré sur les modèles. La mécanique mis en place par ledit plugin est le 
couple html/yaml. Ce couple a été adopté par des plugins « helpers » de la 
communauté :
- Saisies ;
- Vérifier.
J’ai parlé à ce moment là de la nomenclature mis en place par ce plugin qui 
demande une icone, un titre, etc. C’était aussi, si on adopte le fichier yaml, 
pour ne pas casser le fonctionnement qui a été mis en place par ce plugin en 
changeant le contenu de ce fichier YAML.
C’est le même principe par exemple pour le fichier saisies/auteurs.yaml du 
plugin Saisies. ET, il indique les paramètres de la saisie. (Autre exemple : 
saisies/choix_grille.yaml)
Le plugin Insérer Modèles apporte la documentation IN SITU abordée par Rasta.

Le choix du couple html/yaml n’a pas été remis en question dans ces plugins 
largement plébiscités-utilisés par la communauté. ;-) 

Eric, il ne faut pas prendre strictosensus le terme « documentation » ici. La 
page que je pense est plus une mise en forme lisible et compréhensible 
humainement et sans outil de développement (PHPStorm, Sublime Text, Netbeans, 
etc.). 
Les fichiers YAML de saisies sont utilisés pour construire la page 
/ecrire/?exec=saisies_doc et c’est compréhensible. 
Ces fichiers YAML sont des données structurées. Il nous suffit d’en faire ce 
que nous voulons.
Le PHPDoc est documentation pour développeurs. Pas pour utilisateurs lambda. 
Pourquoi mettre en place une nouvelle écriture dans les fichiers html ? Même 
une « pseudo » écriture YAML. Pseudo dans le sens où ce n’est pas dans un 
fichier yaml. Je comprends l’alerte de Rasta sur le fait d’avoir « 2 » fichiers 
à maintenir. C’est sûr. Mais on le fait déjà tous pour les saisies. Ça ne 
choque personne. On enfonce pour moi ici des portes ouvertes.

Je rejoins l’avis de Rasta : du PHPDoc, c’est un parser supplémentaire. 
Par contre… Mon but n’est pas de faire mon truc dans mon coin. Mais d’amener 
une solution qui pourra être utile à l’ensemble des utilisateurs de SPIP.

Le fait de mettre en place le couple html/yaml permet d’apporter de nouvelles 
possibilités d’utilisation. Oui, on est d’accord, il faut installer le plugin 
YAML. Mais ça devient une habitude pour tout le monde, non ? :-D 
(Je ne crée plus de sites sans l’ajout des plugins Saisies, Vérifier, YAML, 
SPIP Bonux et… Info SPIP)

Je comprends vos alertes. Mais encore une fois, il faut faire simple et rester 
dans ce que la communauté propose déjà. 

Voilà pour le moment, je répondrai à vos autres questions au fil de l’eau.

Teddy

> Le 27 sept. 2019 à 19:56, Gildas Cotomale <gildas.cotom...@gmail.com> a écrit 
> :
> 
> Salut Teddy :)
> 
> Je cherche une solution me permettant de faire une petite documentation 
> "automatique" des modèles disponibles sur un site SPIP.
> 
> Alors, qu'entends-tu par "documentation" ? Ou plus précisément, quel public 
> vise-tu et pour quel usage ? (je sais que dit comme ça, c'est un peu cavalier 
> mais ce qui est clair pour toi ne l'est pas forcément pour les autres)
>  
> De préférence une solution un peu comme ce que j'ai mis en place dans le 
> plugin Saisies (cf. 
> https://zone.spip.net/trac/spip-zone/browser/spip-zone/_plugins_/saisies/trunk/prive/squelettes/contenu/saisies_doc.html
>  
> <https://zone.spip.net/trac/spip-zone/browser/spip-zone/_plugins_/saisies/trunk/prive/squelettes/contenu/saisies_doc.html>)
>  ou encore le plugin Vérifier (cf. 
> https://zone.spip.net/trac/spip-zone/browser/spip-zone/_plugins_/verifier/trunk/prive/squelettes/contenu/verifier_doc.html
>  
> <https://zone.spip.net/trac/spip-zone/browser/spip-zone/_plugins_/verifier/trunk/prive/squelettes/contenu/verifier_doc.html>)
> 
> Là par exemple, j'aurais pas deviné que c'est de la doc... au vu du format 
> (fichier HTML avec des boucles et balises SPIP) et l'emplacement (un 
> répertoire squelettes) j'aurais pensé que c'est une noisette ...pour le 
> privé. 
>  
> Pour les modèles, il n'y a rien qui est mis en place pour le moment, sachant 
> que dans ce cas, il n'y a pas de plugin "Modèles". Chaque plugin distribué 
> peut proposer ses propres modèles. 
> 
> C'était le but des modèles il me semble : pouvoir foisonner et se 
> démultiplier presque viralement (ce que proposent les plugins n'étant que des 
> exemples pouvant être surchargés...) https://www.spip.net/fr_article3454.html 
> <https://www.spip.net/fr_article3454.html> ^^ Donc il ne saurait y avoir de 
> lieu/plugin recensant tous les modèles dans la nature. 
> Les modèles étant découverts à la volée (ils ne sont pas "déclarés" par 
> quelque "pipeline" mais recherchés dans un "chemin" donné quand ils sont 
> rencontrés dans le corps du texte) je doute qu'on puisse faire du recensement 
> valide (en dehors d'avoir la liste des modèles découverts sur une 
> installation) 
> 
> Le plugin "Insérer les modèles" demande à ce que si l'on désire qu'un modèle 
> puisse être insérer par son interface, ledit modèle doit avoir un fichier 
> "modele.yaml" correspondant (le fameux couple html/yaml).
> [...]
> cf. 
> https://contrib.spip.net/Comment-declarer-un-modele-pour-le-plugin-Inserer 
> <https://contrib.spip.net/Comment-declarer-un-modele-pour-le-plugin-Inserer> 
> Il lui manquerait peut-être un champ descriptif pour avoir quelque chose de 
> plus didacticiel. 
> 
> De mon point de vue, "Insérer modèles" est aux modèles ce que "Saisies" est 
> aux formulaires ou "Champs-Extras" aux tables/objets... (qui s'appuient aussi 
> sur du YAML j'ai cru voir) 
> Personne n'a jamais eu besoin d'un champ descriptif je pense, mais ça devrait 
> pouvoir se rajouter. facilement. 
> Pour en revenir au sujet, je ne le voyais pas comme de la doc non plus (bon 
> c'est vrai que le format YAML est auto-descriptif et amicalement-humain, mais 
> du coup, comme "doc", c'est plutôt un "mémento" pour les ceux qui lisent les 
> fichiers sources... le plugin se basant sur cette doc pour générer un 
> assistant de saisie, pas un didacticiel sur le modèle...)
> 
> Pour moi, une "documentation" de modèle, à destination des rédacteurs (car 
> moi je préfère aller voir le code et le modifier pour adapter à mes besoins) 
> seraient plutôt comme (on y décrit tous les paramètres du point de vue 
> utilisateur) : 
> - https://contrib.spip.net/Plugin-Modeles-media 
> <https://contrib.spip.net/Plugin-Modeles-media> 
> - https://contrib.spip.net/Modele-doc-unifie 
> <https://contrib.spip.net/Modele-doc-unifie>
> - 
> https://contrib.spip.net/Cite-des-modeles-pour-les-references-bibliographiques
>  
> <https://contrib.spip.net/Cite-des-modeles-pour-les-references-bibliographiques>
> - https://contrib.spip.net/Modele-exergue 
> <https://contrib.spip.net/Modele-exergue> 
> - etc. 
> 
> La communauté SPIP va sur une utilisation généralisée des fichiers YAML. 
> Est-ce qu'il est envisageable de mettre ce couple modeles/fichier.html + 
> modeles/fichier.yaml en place pour l'ensemble des modèles ?
> C'est du travail, certes. Mais cela permettrait d'avoir facilement la 
> connaissance des modèles disponibles sur un site SPIP. On pourra ainsi 
> reprendre la mécanique de page de doc : ercire/?exec=modeles_doc
> 
> Des avis sur le sujet ? :-) 
> 
> Spipement,
> 
> Teddy aka Ybbet
> 

----
spip-zone@rezo.net - https://listes.rezo.net/mailman/listinfo/spip-zone

Répondre à