Readme et lien documentation

Dev
#1

Hello,

J’ai vu fleurir ces derniers jours pas mal de readme pour les plugins.
C’est cool pour certains plugins qui n’ont pas de documentation sur Contrib.
Mais ça serait mieux si on pouvait référencer cette documentation via le lien de documentation affiché dans la page d’administration des plugins ou dans celle de Plugins SPIP.

Le mieux pour faire cela serait de détecter la présence d’un readme automatiquement.
Mais cela va demander à modifier SVP et Plugins SPIP, ce qui est possible mais pas immédiat.

Dans l’intervalle, on pourrait faire un truc simple à savoir mettre le lien vers le readme dans l’attribut documentation du paquet.xml.
Ainsi sans rien changer, on obtiendra le lien vers le readme partout où est affiché actuellement le lien documentation.
Bien entendu, si la documentation existe sur Contrib ou ailleurs il faut continuer à la privilégier.

Qu’en pensez-vous ?

#2

En réflechissant à moyen terme, j’en viens à me demander s’il ne faudrait pas mieux que les doc soient dans le README, ce qui permettrait de documenter au fur et à mesure des commits, et donc ne pas avoir à actualiser la doc uniquement après un tag, ce qu’on n’oublie parfois. Ceci n’empecherait pas, évidemment, d’afficher la doc sur contrib en lisant le README.

#3

Cette discussion me fait penser à ce que je proposais déjà il y a un certain temps : afficher le contenu du README du plugin sur contrib (à l’aide du plugin markdown) si le plugin n’a pas d’article de doc. Je pense vraiment que ça serait une bonne piste :slight_smile:

spip contrib et markdown
#4

Oui alors là c’est une solution qui est intéressante car on rien à changer dans le lien de documentation qui pointerait toujours vers la doc Contrib.
Par contre, je ne vois pas bien comment faire ça au mieux.

Tu imagines qu’on crée un article sur Contrib dans la rubrique du plugin et on a un mécanisme pour peupler le contenu de l’article voire le mettre à jour si on détecte des différences ?
Ce qui serait bien c’est que les mécanismes de Contrib puissent être conservés et que cet article soit juste un cas particulier de remplissage.

Ta vision ?

#5
  1. Lorsqu’on crée la rubrique, on identifie le prefixe
  2. On recherche dans le ZIP le README, et on le met comme article, avec un numero de version associé en cextras
  3. Régulièrement (à voir la fréquence) ou bien grâce à un mecanisme de trigger, on vérifier le numéro de version entre le dernier zip et l’article > on met à jour
#6

@maieul : oui merci mais ça c’est la partie qui me paraissait la plus évidente.

Ma vraie question était : est-on bien d’accord que pour avoir ce mécanisme il faut au préalable manuellement :

  • créer une rubrique pour le plugin dans la rubrique correspondant à la catégorie
  • créer un article en fixant son titre
  • et lancer le premier peuplement du contenu de l’article via un bouton qui ne serait présent que si le readme est détecté, donc que si le plugin fait partie du référentiel, donc que si le plugin a un tag !!!

Après, oui un cache avec le md5 du contenu permet de faire les mises à jour ou de les proposer selon ce que l’on préfère.

A ce titre, je pense qu’il faut qu’on prenne vraiment l’habitude de créer un tag avant de commencer à documenter le plugin. J’ai pas mal d’erreurs remontées par mes checks qui viennent de l’existence d’un article de plugin sans que celui-ci ne soit identifié dans le référentiel.

#7

Moi pour l’instant j’aurais plutôt vu de pas mélanger les genre du tout (ce qui impose des mécanismes de synchro chiant à maintenir et super spécifique) et que le readme soit afficher tel quel sur la page de la rubrique-plugin (et non pas dans une sous-page). À voir ensuite si ça s’affiche par ex seulement quand on a pas sélectionné un « article principal » pour la rubrique en question, auquel cas c’est ce dernier qui prend toujours la main.

On doit sûrement pouvoir demander à l’API gitea de donner le contenu de ce fichier directement sans devoir télécharger et dézipper des choses. Après faut le passer à markdown (ya un filtre dans le plugin idoine) et hop on l’affiche direct.

–
RastaPopoulos

1 « J'aime »
#8

Ouep, je viens de tester je peux récupérer le fichier readme.md en base64 et en plus son sha.
Donc on a tout pour l’afficher.
Néanmoins, comme on court-circuite les rubriques quand il y a un article unique ou d’accueil, je ne pense pas que ce soit une bonne idée de l’inclure dans la page de la rubrique-plugin.
Je pense qu’il vaut mieux garder la logique actuelle d’un article et même si c’est un peu plus compliqué concevoir un mécanisme de mise à jour avec le sha.

#9

Bon alors par contre va falloir décider si c’est README.md ou readme.md car c’est pas la même chose pour l’API de Gitea.

#10

Bon, j’ai un peu creusé le sujet.
J’ai une API qui permet de récupérer, si il existe, le contenu du readme en clair (car il est renvoyé en base64), son sha et sa taille.
Donc pour remplir un article ou l’afficher direct en MD ça ne pose pas de souci (sauf qu’il faudrait que le plugin Markdown soit migré en spip 4).

Mais j’ai un souci conceptuel dans la façon de gérer l’existence du readme et de ne pas se poser la question à chaque affichage en utilisant une API.

Normalement l’existence d’un readme est lié à une branche git, donc à un tag, donc à un paquet au sens de SVP. L’idéal serait alors d’avoir cette information compilée dans le archives.xml et donc incluse dans les tables plugins et paquets.
Mais pour cela il faut modifier le Débardeur et SVP (ça serait aussi l’occasion de rajouter le nom du tag à l’origine du paquet).

Après, si on se concentre uniquement sur Contrib on peut imaginer que l’information peut être associée à la rubrique-plugin en définissant un mécanisme automatique de mise à jour (on screen toutes les rubriques plugin régulièrement mais ça fait beaucoup d’appels d’API).
Et la question est aussi de savoir quel readme on va chercher : celui du master ou d’une branche ou d’un tag donné surtout quand on a souvent des masters qui ne génèrent pas de tag ?

Je suis un peu perplexe pour tout dire, c’est largement faisable mais faut bien détourer les spécifications.

#11

Mais pour cela il faut modifier le Débardeur et SVP (ça serait aussi l’occasion de rajouter le nom du tag à l’origine du paquet).

+1 pour ajouter l’infos directement dans le XML + les tables, et ne pas avoir à scanner quoi que ce soit ensuite.
et +1 pour ajouter explicitement de quel tag ou branche vient un paquet publié (dans un champ tag_ou_branche ou autre nom, c’est pas obligatoirement tag suivant le dépôt, en théorie)

Après, si on se concentre uniquement sur Contrib on peut imaginer que l’information peut être associée à la rubrique-plugin en définissant un mécanisme automatique de mise à jour (on screen toutes les rubriques plugin régulièrement mais ça fait beaucoup d’appels d’API).
Et la question est aussi de savoir quel readme on va chercher : celui du master ou d’une branche ou d’un tag donné surtout quand on a souvent des masters qui ne génèrent pas de tag ?

Je suis un peu perplexe pour tout dire, c’est largement faisable mais faut bien détourer les spécifications.

C’est une bonne question. Pour moi c’est pas le master, car là on doit parler au grand public. Donc c’est :

  • soit celui de la dernière release (le dernier tag posé)
  • soit celui de la dernière release stable (encore plus réduit, mais peut-être trop vu que tout n’est pas toujours en stable mais pourtant bien à documenter quand même)

Plutôt partant pour le premier, c’est déjà assez précis : une personne a volontairement fait un tag donc rendu la chose publique.

Après pour revenir à un peu plus haut, moi je suis par défaut toujours très réticent à tout ce qui doit doublonner de l’information, à forcer à maintenir des synchronisations ensuite. Pour moi ce genre de comportement ne devrait arriver qu’en tout tout dernier recours quand on a vraiment pas le choix, et toujours réfléchir au max à ne pas avoir à gérer des synchros et des doublons de contenu.

On peut parfaitement afficher une rubrique en public même si rien dedans, il suffit de mettre {tout} dans la boucle par ex, pour les squelettes de la compo rubrique-plugin. Et donc ensuite afficher directement sur cette page le readme quand on le décide (là aussi il faut définir la spec, mais c’est un choix d’ergo d’ailleurs, ya un pad pour ça hihi). Genre on l’affiche si ya aucun article de type « documentation » par ex (s’il y a un seul article ça y va direct, s’il y a plusieurs articles ça affichera les listes de ces contenus suivant leur type et parfois readme ou pas, ce qui permet aussi d’affiche readme + des articles de conception ou d’actus si ya aucun article documentation, mais dès qu’il y en a un pas de readme).

–
RastaPopoulos

#12

En fait, on a l’information deux fois dans la table paquet : dans la version et dans le nom de l’archive.

Oui, c’est simple car dans la table plugin on a le champ vmax qui désigne la version la plus « récente » parmi les paquets du plugin. Je pense que c’est le plus simple si on ne prend pas le master.
Pour l’état je serais d’avis de ne pas en tenir compte.

Après pour la synchro, c’est pas le problème à mon avis car de toute façon, si on prend le dernier tag il faudra bien faire évoluer le readme affiché.
Le sujet c’est plus la méthode d’affichage : un « objet » readme à part, un champ dans la rubrique ou un article de type readme qui a l’intérêt de conserver intact toute la mécanique actuelle.
Et de toute façon, pour moi il doit toujours y avoir une opération manuelle qui permet de décider si on veut documenter le plugin que ce soit par son readme ou autre (il faut a minima créer une rubrique-plugin). Et je dirais même qu’il faudrait un workflow pour dire, mon plugin, je veux le documenter avec son readme comme « article » principal.

#13

Bon après réflexion j’ai l’impression qu’il faudrait ajouter le readme quelque part dans le xml compilé par le Debardeur.
Par exemple, en rajoutant une balise dans la balise englobante <archive> ou celle incluse <zip>.
A partir de là il suffirait de faire évoluer SVP pour acquérir cette information dans un champ dédié des tables paquets et plugins.

@cerdic tu crois que ça pourrait être possible ? Par exemple dans la fonction debardeur_analyser_zip qui renvoie le tableau $infos qui contient les informations qui seront incluses dans le archives.xml.

Après, faut réfléchir si on ne veut pas non plus savoir si il y a un changelog pendant qu’on y est.

#14

Le 28/05/2022 à 21:09, Eric Lupinacci via Discuter de SPIP a écrit :

Après pour la synchro, c’est pas le problème à mon avis car de toute façon, si on prend le dernier tag il faudra bien faire évoluer le readme affiché.

Je n’ai pas compris cette phrase. :slight_smile:

Justement pour moi ya pas du tout besoin de synchro. Si on est dans un cas où on veut le readme (à peaufiner mais en gros pas d’autres articles « docu » etc), alors on prend l’URL du readme du paquet le plus récent trouvé dans les infos, on lit le contenu et on l’affiche, et point basta. Ya rien à faire évoluer ensuite. Quand plus tard le « dernier tag » (donc le dernier paquet) change bah tout simplement ça lira alors une autre URL et ça affichera forcément autre chose. Qu’il y ait un cache c’est une chose (et avec les squelettes il y a déjà du cache, dont on peut décider le temps), et on peut ajouter un niveau de cache en gardant ce qui est aspiré de l’API dans tmp/ un moment, mais c’est très différent de garder réellement en fixant en SQL du contenu à faire synchroniser ensuite.

En pseudo code va-vite

<BOUCLE_test_docu(ARTICLES){type=documentation}{0,1}>
</BOUCLE_test_docu>
   <BOUCLE_dernier_paquet(PAQUETS){!par version}{0,1}>
     [(#URL_README|recuperer_gitea|markdown)]
   </BOUCLE_dernier_paquet>
<//B_test_docu>

Et voilà, tant que c’est la même URL car venant du même paquet, recuperer_gitea ne le récup qu’une fois et après ça va chercher ce qui est déjà dans tmp/.
Et quand le dernier paquet plus récent change, bah c’est forcément une autre URL.

Bien plus simple à maintenir il me semble, sans complication, et bien optimisé quand même.

–
RastaPopoulos

#15

Mais du coup le REAMDE ne pourra pas être retrouvé par le moteur de recherche de SPIP, non ?

#16

Oui exact, ça peut fonctionner ça si on appréhende le sujet en ce disant que le readme n’est jamais plus qu’un cache sur Contrib.
Mais bon, j’ai une fonction qui récupère le readme via l’API, il n’y a plus qu’à coder le reste… Moi je passe la main pour un moment.