[SPIP Zone] Documentation des modèles d'un site SPIP

Archives Zone
1

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

Spipement,

Teddy aka Ybbet

2

Salut Teddy :slight_smile:

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

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

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

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

Spipement,

Teddy aka Ybbet

3

Gildas, le YAML sert pas à aller le lire hein… il sert à afficher son
contenu dans une page, donc bien pour les rédacs, d'où les squelettes
qui l'affiche. Quand aux docs, ou explications, c'est toujours mieux "in
situ" qu'en devant aller les chercher/lire ailleurs, un manuel séparé,
sur un autre site que là où on est en train d'écrire. En théorie une
interface ergonomique n'a pas besoin de doc, disons le moins possible en
tout cas, et dès qu'il y a besoin, il faut toujours préférer la placer
pile au bon endroit où la personne en a besoin.

Autant pour Saisies et Vérifier je vois pas trop l'intérêt car ce n'est
que pour les développeurs. Mais pour les modèles là c'est important que
les rédacteurs puissent savoir *au moment d'écrire*, ce qu'ils ont à
disposition, quels sont les paramètres possibles, etc. On ne devrait
jamais devoir partir lire ailleurs pour savoir ça, je suis assez d'accord.

--
RastaPopoulos

4

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

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

Ça semble très utile
mais il n'y a aucune nécessité à rendre cela obligatoire.

JL

5

Hello,

Le sam. 28 sept. 2019 à 12:25, RastaPopoulos <rastapopoulos@spip.org> a écrit :

Gildas, le YAML sert pas à aller le lire hein… il sert à afficher son
contenu dans une page, donc bien pour les rédacs, d’où les squelettes
qui l’affiche. Quand aux docs, ou explications, c’est toujours mieux « in
situ » qu’en devant aller les chercher/lire ailleurs, un manuel séparé,
sur un autre site que là où on est en train d’écrire. En théorie une
interface ergonomique n’a pas besoin de doc, disons le moins possible en
tout cas, et dès qu’il y a besoin, il faut toujours préférer la placer
pile au bon endroit où la personne en a besoin.

Autant pour Saisies et Vérifier je vois pas trop l’intérêt car ce n’est
que pour les développeurs. Mais pour les modèles là c’est important que
les rédacteurs puissent savoir au moment d’écrire, ce qu’ils ont à
disposition, quels sont les paramètres possibles, etc. On ne devrait
jamais devoir partir lire ailleurs pour savoir ça, je suis assez d’accord.

L’aspect développeur ou pas ne me parait une raison valable pour ne pas commenter.
Ces derniers temps, par exemple dans N-Core, j’ai adopté une simili écriture à la PHPDoc pour commenter les modèles ou inclusions comme suit :

[(#REM) <!--  CONTENEUR_COMPILER

   Compile les noisettes d'un conteneur fourni en paramètre de l'inclusion.
   Cette inclusion est utilisée pour compiler récursivement une noisette conteneur.
   Elle peut être surchargée pour s'adapter au mieux au stockage du plugin utilisateur.

   @api

    @param string plugin
           Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
           un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
   @param string  id_conteneur
          Identifiant du conteneur.
   @param string stockage
           Identifiant du service de stockage à utiliser si précisé.
-->]

On pourrait d’ailleurs imaginer de développer une extension à PHPdoc pour les HTML.

++

Eric

6

Re,

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.

Bof, je vois vraiment l’intérêt d’un fichier YAML pour faire de la documentation.
Surtout pour donner des informations presque inutiles comme le titre et l’icone.
Ce qui est utile pour un modèle ou plus généralement une inclusion c’est les paramètres.
C’est pour ça qu’une en-tête à la PHPDoc me parait nettement plus adaptée.

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 ?``

Euh bof sur le YAML.
Il demande à utiliser une librairie spéciale qui n’est même pas intégrée nativement dans le Core.

7

Le sam. 28 sept. 2019 12:25, RastaPopoulos a écrit :

Gildas, le YAML sert pas à aller le lire hein… il sert à afficher son
contenu dans une page, donc bien pour les rédacs, d’où les squelettes
qui l’affiche.

Si on veut… Je faisais juste remarquer que c’est un autre système de balisage qui est justement plus facile à lire (en tout cas comparé à du JSON ou autres formes de sérialisation, et pourtant on peut programnaticalement le transformer en les autres) et accessoirement plus léger (que du XML qui peut avoir les mêmes usages.)
Afficher du contenu dans une page est l’usage qui en est fait ici, mais je l’utilise aussi par exemple pour de la configuration (avec TOML ce sont de bons remplaçants des infâmes Ini, surtout pour décrire simplement des transformations/traitements) …et c’est bien l’usage qu’en fait Insérer Modèles : dis moi les paramètres de ton modèle (le côté documentation) et comment les traduire en formulaires saisies (qui génère l’affichage) placées dans un cadre latéral. Sur le résultat, dans ce cadre ci, nous sommes bien d’accord.

Quand aux docs, ou explications, c’est toujours mieux « in
situ » qu’en devant aller les chercher/lire ailleurs, un manuel séparé,
sur un autre site que là où on est en train d’écrire.

Cela me rappelle du coup que SPIP a un système d’aide (maintenant en plugin et toujours dans la dist) extensible par les plugins… C’est aussi là une source de documentation interne qui n’est pas exploité.

En théorie une
interface ergonomique n’a pas besoin de doc, disons le moins possible en
tout cas, et dès qu’il y a besoin, il faut toujours préférer la placer
pile au bon endroit où la personne en a besoin.

C’est probablement pour ça que je n’ai jamais rien compris aux interfaces dites ergonomiques [attention, c’est une perception personnelle et un potentiel début de troll]

Autant pour Saisies et Vérifier je vois pas trop l’intérêt car ce n’est
que pour les développeurs.

Je suis contre l’idée que les développeurs n’ont pas besoin de doc ; ça donne rarement de bons résultats…

Tiens, parlant de docs pour Saisies et Vérifier, je viens de voir que quand ils sont installés et que j’active le menu Développement bah qu’ils ont chacun leur entrée dans ce menu, et que leur page me réclame le plugin YAML. Une fois fait, je retrouve la première partie (paramètre de chaque saisie) de https://contrib.spip.net/Reference-des-saisies et (idem) https://contrib.spip.net/Reference-des-verifications D’ailleurs, comment sont générées ces pages du privée et est-ce que ça peut se généraliser à d’autres plugins facilement ? C’est fait avec le « _doc.html » initialement mentionné ?

Mais pour les modèles là c’est important que
les rédacteurs puissent savoir au moment d’écrire, ce qu’ils ont à
disposition, quels sont les paramètres possibles, etc.

Donc, il faudrait que les auteur(e)s de plugin qui proposent des modèles ajoutent également le .yaml pour Insérer Modèles et croisent les doigts pour que les surcharges restent compatibles.

Ceci dit, on voit bien l’importance de définir la cible (pour toi il ne s’agit que des rédacteur(e)s alors qu’une autre personne pourrait penser qu’on s’adresse aux gens qui utilisent la balise #MODELE{} etc.)
Et bien définir le besoin (s’il s’agit de l’aide à la rédaction ou de l’amélioration du plugin d’insertion des modèles, ce n’est pas pareil que de vouloir recenser tous les modèles existants partout comme je l’avais compris) :smiley:

On ne devrait
jamais devoir partir lire ailleurs pour savoir ça, je suis assez d’accord.

–
RastaPopoulos

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

8

Les modèles sont déjà décrits avec du YAML quand on veut qu'ils soient
utilisables avec Insérer modèles qui génère des formulaires d'aide à
l'insertion. Donc je vois moyen l'intérêt de documenter deux fois les
mêmes choses.

Si tout était en PHPDoc (alors qu'en plus c'est pas du PHP mais des
squelettes mais ok soit un simili PHPDoc), il faudrait AUSSI une
librairie supplémentaire pour parser le PHPDoc et ainsi pouvoir générer
de la documentation automatique in situ au bon endroit pour les rédacteurs.

Donc vu que dans les deux cas faut une lib + que ya déjà un début de
description et d'utilisation avec YAML pour un certain nombre de modèles
existants, autant continuer dans la même voie.

Par contre ya aucune obligation, et ça n'a pas de rapport avec le core
pour l'instant (à moins d'intégrer une aide rédacteur bien faite pour
les modèles mais c'est loin d'être le cas pour l'instant). Donc bah si
Ybbet t'as besoin des YAML tu installes Insérer Modèles et tu complètes
les plugins que t'aimes qui te fournissent des modèles pour leur ajouter
le YAML descriptif… Un truc comme ça.

--
RastaPopoulos

9

Si on peut éviter de lire à moitié… je parle de doc IN SITU. Jamais dit
qu'il y avait pas besoin de doc du tout pour le reste…

Saisies et Vérifier c'est pour des devs, donc je vois moyennement
l'intérêt de faire des docs "inside" le site sur lequel on travaille, ya
aucune problème à avoir la doc ailleurs justement.

Alors que pour les modèles, c'est là où ya le plus évident besoin d'une
doc automatique et exhaustive in situ, à l'endroit exact où le rédacteur
en a besoin.

--
RastaPopoulos

10

Le sam. 28 sept. 2019 14:19, Eric Lupinacci a écrit :

Re,

Le ven. 27 sept. 2019 à 13:14, Ybbet Spip a écrit :

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.

Bof, je vois vraiment l’intérêt d’un fichier YAML pour faire de la documentation.

Comme le faisait remarquer Rasta plus tôt, la finalité n’est pas à proprement dit de faire de la documentation (bien que là dessus YAML rejoigne PHPDoc ici, ou plus généralement le XML) mais d’afficher une assistance de saisie (un peu comme les boutons du Porte-Plume finalement, mais avec une boîte de dialogue de paramètres)

Surtout pour donner des informations presque inutiles comme le titre et l’icone.

D’où ma comparaison avec le Porte-Plume. Comme tous les trucs de l’interface de rédaction, il faut bien une image (sauf que, les modèles n’étant pas forcément liés à un plugin on ne peut pas envisager d’utiliser les logos de plugin par exemple, et puis on peut avoir plusieurs modèles qui ont besoin d’être différencié visuellement) et un nom/titre (pratique quand on n’affiche pas les images ou quand on a des icônes similaires…)

Ce qui est utile pour un modèle ou plus généralement une inclusion c’est les paramètres.
C’est pour ça qu’une en-tête à la PHPDoc me parait nettement plus adaptée.

Je trouve que les deux approches se valent : dans tous les cas il faut bien décider où trouver les infos (et là effectivement ta solution me plaît mieux car je n’ai pas deux fichiers à maintenir haha) et leur formalisme (et avec YAML c’est visiblement plus simple tu trouves pas ?)

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 ?``

Euh bof sur le YAML.
Il demande à utiliser une librairie spéciale qui n’est même pas intégrée nativement dans le Core.

En soit ce n’est pas un vrai souci :slight_smile: Ceux qui en ont besoin installeront le plugin qui va bien en attendant que ça rentre dans le Coeur (cf. Cfg et Bonus)
Mais avant (d’en arriver à l’intégration dans le Core) il faut débattre pour obtenir une convention utile à tous (dans ton exemple précédent le PHPDoc doit être peaufiné pour qu’au « parsing » du fichier on puisse reconnaître que c’est relatif à un modèle et qu’on ait aussi toutes les informations pour déduire les saisies qui vont bien…)

++

Eric

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

11

Le 28/09/2019 à 14:13, Eric Lupinacci a écrit :

Ces derniers temps, par exemple dans N-Core, j'ai adopté une simili écriture à la PHPDoc pour commenter les modèles ou inclusions comme suit :

[(#REM)<!-- CONTENEUR_COMPILER
(...)

Il y a justement un plugin assez ancien qui fait ça pour les modèles qui ont un commentaire au début, pour décrire de façon sommaire leur fonctionnement et leurs paramètres par exemple.
Le plugin les affiche dans la colonne de droite.

Je l'utilisais à une époque mais je n'arrive pas à remettre la main dessus...

--
nicod_

12

Cela me rappelle du coup que SPIP a un système d'aide (maintenant en plugin et toujours dans la dist) extensible par les plugins... C'est aussi là une source de documentation interne qui n'est pas exploité.

Hop, c'est documenté quelque part cette doc ? comment un plugin peut-il s'en servir ?

13

Le sam. 28 sept. 2019 17:01, Maïeul a écrit :

Cela me rappelle du coup que SPIP a un système d’aide

Prévu initialement pour fournir l’aide mémoire des raccourcis typographiques

(maintenant en

plugin et toujours dans la dist) extensible par les plugins… C’est
aussi là une source de documentation interne qui n’est pas exploité.

Hop, c’est documenté quelque part cette doc ? comment un plugin peut-il
s’en servir ?

14

Re,

Le sam. 28 sept. 2019 à 15:15, RastaPopoulos <rastapopoulos@spip.org> a écrit :

Les modèles sont déjà décrits avec du YAML quand on veut qu’ils soient
utilisables avec Insérer modèles qui génère des formulaires d’aide à
l’insertion. Donc je vois moyen l’intérêt de documenter deux fois les
mêmes choses.

Si tout était en PHPDoc (alors qu’en plus c’est pas du PHP mais des
squelettes mais ok soit un simili PHPDoc), il faudrait AUSSI une
librairie supplémentaire pour parser le PHPDoc et ainsi pouvoir générer
de la documentation automatique in situ au bon endroit pour les rédacteurs.

Oui dans ce cas là ça se justifie.
Je ne savais pas qu’on avait des YAML pour les modèles avec le plugin Insérer Modèles.
Mais je trouve quand même dommage d’avoir une « doc » à part qui ne sert pas en développement.

Donc vu que dans les deux cas faut une lib + que ya déjà un début de
description et d’utilisation avec YAML pour un certain nombre de modèles
existants, autant continuer dans la même voie.

Oui mais c’est dommage de limiter cela aux modèles et de ne pas étendre aussi au développement.
Il n’y aurait pas une façon de combiner les deux, à savoir, insérer du YAML dans la balise commentaire qui serait lisible d’une part pour les développeuers et d’autre part pour une version upgradée de Insérer Modèles. Que ce soit une chaine ou un fichier YAML le parsing et le même et le problème d’une librairie simili-PHPdoc n’existe plus.

En particulier ça permettrait d’avoir des explications pour les inclusions.

++

Eric

15

Le 29/09/2019 à 04:57, nicod_ a écrit :

Le 28/09/2019 à 14:13, Eric Lupinacci a écrit :

Ces derniers temps, par exemple dans N-Core, j'ai adopté une simili écriture à la PHPDoc pour commenter les modèles ou inclusions comme suit :

[(#REM)<!-- CONTENEUR_COMPILER
(...)

Il y a justement un plugin assez ancien qui fait ça pour les modèles qui ont un commentaire au début, pour décrire de façon sommaire leur fonctionnement et leurs paramètres par exemple.
Le plugin les affiche dans la colonne de droite.

Je l'utilisais à une époque mais je n'arrive pas à remettre la main dessus...

Insérer modèle (de Joseph)

--
RealET

16

Le 28/09/2019 à 20:34, Eric Lupinacci a écrit :

Il n'y aurait pas une façon de combiner les deux, à savoir, insérer du
YAML dans la balise commentaire qui serait lisible d'une part pour les
développeuers et d'autre part pour une version upgradée de Insérer
Modèles. Que ce soit une chaine ou un fichier YAML le parsing et le même
et le problème d'une librairie simili-PHPdoc n'existe plus.

Ouais j'ai pensé à la même chose tout à l'heure.

Mais sauf que le YAML sert à générer des vraies interfaces pour des
humains rédacs (que ce soit de la doc in situ ou des formulaires
d'insertion), donc multilingues, donc avec des chaines.

Du coup si le⋅a dev dans le code, ille voit un com du genre
[(#REM) yaml
……
description: <:patates:modele_truc_description:>
……
-
  saisie: 'input'
  options:
    nom: 'nb_max'
    label: <:patates:modele_truc_nb_max_label:>
……
]

Bah pour le coup, pour ça va pas lui décrire humainement à quoi ça sert,
va juste voir des identifiants de chaines.

--
RastaPopoulos

17

Le sam. 28 sept. 2019 21:48, RastaPopoulos a écrit :

Mais sauf que le YAML sert à générer des vraies interfaces pour des
humains rédacs (que ce soit de la doc in situ ou des formulaires
d’insertion), donc multilingues, donc avec des chaines.

Du coup si le⋅a dev dans le code, ille voit un com du genre
[(#REM) yaml
……
description: <:patates:modele_truc_description:>
……

saisie: ‹ input ›
options:
nom: ‹ nb_max ›
label: <:patates:modele_truc_nb_max_label:>
……
]

Bah pour le coup, pour ça va pas lui décrire humainement à quoi ça sert,
va juste voir des identifiants de chaines.

Bah rien n’empêche d’avoir plutôt :
[(#REM) yaml
……
description: <:patates:modele_truc_description:>
divers: « Deux ou trois mots en plus parce-que j’ai un item de langue insignifiant »
……

saisie: ‹ input ›
options:
nom: ‹ nb_max ›
label: <:patates:modele_truc_nb_max_label:>
divers: « texte complémentaire parce-que ma chaîne de langue n’est pas assez explicite »
……
]

Je n’ai pas regardé le code, mais j’espère que Joseph ne s’attend pas à un tableau qui n’aurait pas d’entrée inconnue du dictionaire du plugin. Au pire, YAML permet d’avoir des commentaires qui, par chance, ne sont en conflit ni avec HTML ni avec PHP …ni avec SPIP si on prend soin de bien mettre au moins un espace :
A[(#REM) yaml
……
description: <:patates:modele_truc_description:>

Deux ou trois mots en plus parce-que j’ai un item de langue insignifiant

……

saisie: ‹ input ›
options:
nom: ‹ nb_max ›
label: <:patates:modele_truc_nb_max_label:>

texte complémentaire parce-que ma chaîne de langue n’est pas assez explicite

……
]

18

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é. :wink:

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 ? :smiley:
(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.cotomale@gmail.com> a écrit :

Salut Teddy :slight_smile:

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

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

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

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

Spipement,

Teddy aka Ybbet

19

Bof, s'il faut toujours aller voir dans les chaines de langue pour voir le descriptif, ça n'aide pas vraiment.

--
nicod_

20

Hello,

Le dim. 29 sept. 2019 à 02:22, Ybbet SPIP <teddy.spip@gmail.com> a écrit :

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é. :wink:

Soit mais je pense qu’on mélange les choses.
Dans ces plugins le YAML apporte de la configuration avant tout.
L’utilisation du YAML est donc légitime à mon sens et le langage permet d’être assez compréhensible même si je pense qu’on devrait plutôt utiliser du JSON.
A ce propos, les YAML ne sont jamais expliqués au travers d’un schéma ce qui est possible aujourd’hui et donc on ne sait jamais ce qu’il est possible d’y mettre. J’ai corrigé ça dans le noiZetier mais ça devrait être pratique plus régulière.

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

Soit, je ne suis pas totalement abruti :wink:

Les fichiers YAML de saisies sont utilisés pour construire la page /ecrire/?exec=saisies_doc et c’est compréhensible.

Ca c’est toi qui le dit.

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.

Tu plaisantes là franchement. Mais j’y reviendrais plus bas.

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.

Mais non on le fait pas tous pour les saisies.
Y a rien de systématique et ce n’est pas obligatoire.
Et franchement si je dois aller voir dans un YAML la liste des paramètres sans explication, je ne vois pas l’intérêt.
Donc ton postulat de départ est faux.

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.

Oui si on veut.
Remarque ça nous arrive parfois de faire des plugins et de développer des trucs nouveaux…
Mais j’ai déjà répondu à ça et je trouve qu’on pourrait éviter d’avoir deux fichiers et intégrer le YAML dans le HTML.
Parce que ce YAML N’EST PAS de la configuration.
Le vrai souci qu’à exprimé Rasta c’est la traduction.

Maintenant, me dire que la doc utilisateur et dévelopeur est différente pour ce cas, ça me fait doucement rire : c’est quoi la différence pour décrire le but de l’inclusion et l’utilisation de ses paramètres quand on est « rédacteur dans le privé » et « développeur » ?
Aucune.
Donc on est dans un cas un peu particulier où une seule documentation pourrait suffire.

Après il faut être pragmatique :

  • ce besoin est au moins aussi important pour les développeurs que pour les rédacteurs.
  • que ça pourrait s’appliquer aussi aux inclusions hors modèles
  • que l’on pourrait réfléchir in fine à rajouter ces informations à l’autodoc
  • que la traduction n’est surement pas le souci le plus critique pour les utilisateurs et que donc du texte en français suffirait, sans chaines de langue inutiles qui donnent encore du travail aux traducteurs pour une utilité plus que douteuse.

C’est pourquoi je ferais plutôt :

  • une balise #REM reconnaissable comme une doc
  • une description type phpdoc pour l’inclusion avec du YAML qui serait extrait de la balise avec des textes sans chaines de langue.
  • je ferais disparaitre les YAML externes à terme pour Insérer Modèles car il servirait plus à rien, le plugin pouvant extraire les données du HTML.

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 ? :smiley:
(Je ne crée plus de sites sans l’ajout des plugins Saisies, Vérifier, YAML, SPIP Bonux et… Info SPIP)

Je ne sais pas d’où tu sors ça.
Le YAML est bancal dans SPIP aujourd’hui.
Le Core ne le procure pas, ce qui est pour moi une erreur à partir du moment où on pense que ce format est important comme le XML ou le JSON.
Textwheel fournit un morceau de librairie bien dépassé.
Et j’ai refait le plugin YAML pour utiliser les différentes librairies afin in fine de choisir une voie qu’on a jamais choisi.
Je pense qu’on pourrait faire mieux :p.

Et franchement, le JSON est au moins natif en PHP, possède un schéma qui permettrait à terme de valider les formats et peut être fabriqué à partir d’un YAML pour ceux qui sont plus à l’aise avec ce format.
J’avais d’ailleurs fourni un patch de Textwheel en JSON presque fonctionnel et qui nous permettrait de nous passer du YAML dans Textwheel.

++

Eric