Le 27/09/2019 à 13:13, Ybbet Spip a écrit :

Bonjour à tous,

Je cherche une solution me permettant de faire une petite documentation "automatique" des modèles disponibles sur un site SPIP. 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) 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)

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.

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).
Le fichier yaml indique :
- Le nom du modèle ;
- un logo ;
- une icône pour la barre d'édition ;
- la liste des paramètres pouvant être passés au modèle.
cf. 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.

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 ? :-)

Hello

Bon comme tout les commentaires sont partis sur des solutions purement developpeur php a base de php doc et truc dans le genre, je vais rajouter ma vision d’intégrateur qui ne voit donc que le coté front !

Déjà je suis content que quelqu’un s’intéresse a ce point ^^ j’avais déjà abordé le sujet sur irc de la documentation de squelettes, modèles, bref documenter la relation html/css/js le front… vu que dans spip on fait beaucoup dans le template, autant le documenter et un templates c’est du html mm si on apelle des fonctions php via des balise ou filtres boucles…

Un modèle, c’est pareil ça reste du markup en théorie, pourquoi documenter via phpdoc/php ce qui est du html ? Autant documenter dans le html direct de mon avis, comme la plupars actuellement des modèles le sont.

*Le coup de passer par inserre modele et au format yaml, la je dis Attention !!!*

Je m’explique : En tant qu’intégrateur je surcharge quasiement tout les squelettes fournis par spip ou les plugins et les css (parceque j’y suis obligé vu le markup ou les css qui ne convienne pas ou sont bourrés de !important et autres joyeusetées dans le genre ou de nomenclatures toutes différentes ^^, et que je dois adapter à la problématique métier du site ou des demandes) bref le job…

/En aparté, le problème du dossier /modeles est que bien souvent on trouve des choses qui n’aurait pas a être ici, c’est un fourre tout ou pas mal de plugins installables via svp : donc sans controle du contexte d’affichage de ma part vu que pas chartés et stylés par moi. En théorie un modèle c’est insérés dans un champ éditorial, le problème est que l’on peut aussi les appeler depuis un skel, et donc certain-aines depose dans le dossier modèle des portions de skel, qui en théorie devraient êtres dans /inclure. voir /inclure/objet|plugin/xxx.html ça serait plus clair tout de suite quand on est dans son editeur/ide./

insserer modèle fourni au rédacteur-trice l’interface pour les modèles que *je souhaite qu’il/elle puisse utiliser* :

 * et je ne souhaite pas qu’ils puisse utiliser en furetant un modèle
   que je n’ai pas charté et intégré (donc demandé dans le CDC).
     o adapter les termes chaine de langues en fonction du contexte
       metier etc
 * rajouter des paramètres le cas échéant, modifier le markup (ajout
   aria, meta-datas, etc)

Si on suit le concept de documentation via yaml qui remplacerait xml, tout les modèles seront donc accessibles, via inssérer modèle, sans que je puisse controler quoi que ce soit, et depuis le responsive ça pose un gros problème de temps d’intégration si on envisage tout les cas possibles (et donc temps = ouille ).

En continuant donc on peut se dire que la config pourrait lister les modèles et des cases a cocher et autoriser ou non l’affichage dans inssérer modèle soit. Mais donc le webmestre peut à loisir y accéder et activer un modèle qui n’as pas été intégré au design system et dont on ne connait pas le contexte d’affichage ou d’utilisation, ceci peut induire des discussions des tikets, des incompréhensions du genre y’a un bug.

En résumé, l’apparente simplicité de passer par les yaml/xml pour documenter, devient une complexité supplémentaire et un coût d’intégration de mon avis (désolé d’être terre a terre).

*Alors je vais revenir une enième fois a la charge … ^^*

Depuis quelques années maintenant, j’utilise Kss comme méthodologie pour documenter mes css/scss markup (le theme) et ceci est basé sur les commentaires avec un parser de comments qui est déjà prévu pour ça avec un nomenclature simple. L’état actuel des modèles et les sections commentaires de la plupart est quasiement déjà au bon format. On peut le voir sur par exemple les modèle de owl-carousel, ils sont déjà au format kss (pour cause ^^), mais dans d’autres modèles d’autres plugins aussi c’est similaire.

|[(#REM)<!-- # Owl Video player VideoPlayer avec Owl Carousel et oembed @see - http://owlgraphic.com/owlcarousel/index.html#customizing @param objet - @param id_objet - lister les medias vidéos associés a un objet/id_objet @param id_document {array} - peut être un tableau de documents @param id-carousel - selecteur id unique du carousel @param navigation {str} (oui|non) - affiche les boutons précédents suivants @param dots {str} (oui|non) - affiche les point de navigation @param : lazyLoad : true (false par défaut) : ne charge que les images visibles pour optimiser le chargement. @param afficher_thumbnails {str} (oui|non) - Affichage des miniatures de navigation @param thumbs_loop {str} (oui|non) - Rotation infinie des miniatures @param animateIn - une animation css3 , `fadeOut` est la seul fournie par owl, sinon ajouter animate.css @param animateOut - une animation css3 , `fadeOut` est la seul fournie par owl, sinon ajouter animate.css @todo - Corriger : en mode touch/drag le player vidéo n'est pas détruit du coup plusieurs vidéos peuvent jouer en mm temps -->] |

J’ai déjà fait des tests il y’a quelques temps dans ce sens, et j’avais commencé une intégration de la lib en plugin spip, pour les styles, mais voyant que en en parlant ça ne defrayait pas non plus un engouement terrible ;-) , j’ai préféré continué sur un dev hors spip plus polyvalent dans mon cas. Cela dit c’est une lib php et des class et ça retourne un objet donc rien de bien dur a renvoyer a un template spip.

https://github.com/kss-php/kss-php

il y’a quelques modifications minimes a faire dans le parser pour que les commentaires spip soient pris en charge, prendre en charge le format html et adapter la regex des comments a spip, mais comme c’est une classe ça s’étend facilement.

bref au final on est pas loin de la syntaxe des phpdoc ou javadoc et on pourrait documenter dans le html, ce qui reste de mon avis la solution la plus simple et efficace.

​

--
Bonne journée
Arnaud B. (Mist. GraphX)

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

Répondre à