Framavox

Action 10 - Gestion des docs externes

Maïeul
Maïeul Public Seen by 25

On a eu le cas récemment d'une personne qui souhaite conserver sa doc dans le README de son dépot github. C'est relativement légitime. Il y a deux solutions pour gérer cela:
1. on fait un lien vers la doc
2. on fait un script qui à intervalle régulier synchronise la doc.
La solution 2 me parait meilleur, notamment pour la recherche

Lupinacci Eric

Lupinacci Eric April 18th, 2019 18:13

Je pense que si on fait tout le travail actuel c'est aussi pour encourager les gens à écrire de la doc et en particulier sur Contrib.
Ce cas existe déjà, il est géré par le lien de documentation du paquet.xml et c'est Plugins SPIP qui renvoie sur le lien externe. Si on intégrait Plugins SPIP à Contrib alors on aurait encore moins besoin de se poser cette question.

Dans tous les cas je n'y suis pas favorable.

RastaPopoulos

RastaPopoulos April 19th, 2019 11:45

Ça peut être à 10000 endroits différents une documentation externe (un dépôt git, un site dédié, sur Seenthis…), il n'y a strictement aucun moyen de récupérer ça ne manière certaine et pérenne. Donc non faut pas faire ça pour moi. Surtout que sauf super exception je suis pour tenter de supprimer le maximum de synchronisation possible, et ne jamais avoir plusieurs fois la même info en plusieurs endroits : c'est mal.

Pour l'instant c'est le lien dans Plugins et c'est très clair.

Si on intègre à Contrib, comment ça se passerait du coup d'ailleurs, puisque ça serait une rubrique-plugin uniquement, mais qui n'aurait jamais aucun contenu de toute la vie. Donc ça veut dire que ces rubriques-plugins vides devraient être visibles quand même sur le site (alors que par défaut SPIP ne sort pas les rubriques vides ! mais faut l'annuler que pour celles là…), dans les listes et dans la rercherche.

Maïeul

Maïeul April 19th, 2019 12:15

oui, c'est bien la quesiton que je pose. Comment on fait ?

Lupinacci Eric

Lupinacci Eric April 19th, 2019 16:30

Non on ne créerait pas de rubrique-plugin si aucune documentation n'existe.

En fait, intégrer Plugins SPIP à Contrib revient (presque) uniquement à rajouter la page plugin.html à Contrib. La page plugin.html n'a besoin d'aucun article pour être affichée puisqu'elle est créée à partir des tables plugins et paquets.
Donc pour un plugin donné, on aurait :
- tout le temps la page plugin.html affichable,
- et parfois des articles matérialisés par article.html et pouvant avoir une composition spécifique. Dans ces pages on a un bloc "plugin" qui rappelle les infos du plugin (comme mise en place récemment) et on peut passer facilement à la page plugin.html.

Pour la recherche qu'on intègre ou pas la page plugin.html on peut chercher dans les articles mais aussi dans les tables plugins et paquets comme pour Plugins SPIP. De fait, on peut quand même renvoyer un plugin qui n'a pas de doc sur Contrib via un système d'onglet : un onglet plugin, un onglet doc...
C'est sur qu'avec la page plugin.html c'est mieux.
Mais je trouve ça pas mal que la recherche sur Contrib renvoie la même chose à minima que sur Plugins SPIP puisque c'est possible. Voilà aussi pourquoi il faut se poser la question du besoin de Plugins SPIP in fine.

RastaPopoulos

RastaPopoulos April 19th, 2019 17:05

voui ok je suis d'accord

cy_altern

cy_altern April 20th, 2019 15:13

OK pour moi: l'important me semble que la recherche sur contrib ramène (à minima) tous les plugin.html (= les résultats actuels de Plugins SPIP)

Y

YannX April 21st, 2019 09:25

Je reagis au cas d'un plugin ayant sa documentation (par l'auteur) ailleurs...
Que je sache, tout contributeur peut aussi vouloir écrire sa propre documentation d'usage d'un plugin qu'il n'a pas ecrit, et vouloir la partager.. est-ce interdit ?
Donc garder un article lien virtuel vers une documentation externe :
- conserve la structure /actuelle/ d'une rubrique par plugin sur Contrib
- permet toute forme de documentations complémentaires....
(ou bien suis-je en train d'enfoncer une porte ouverte ?)

Lupinacci Eric

Lupinacci Eric April 21st, 2019 14:08

C'est l'objectif du lien de documentation contenu dans le paquet.xml. Il est inutile à mon avis de refaire cela en plus dans Contrib. En plus, si on s'accorde pour ajouter la page plugin.html dans Contrib, on aura tout ce que l'on veut sans rien rajouter.

Maïeul

Maïeul April 25th, 2019 12:06

Je précise ma question de base : si la doc est hors contrib, elle sera certe référencées, mais elle n'apparaitra pas dans les résultats de la recherhe full text

Lupinacci Eric

Lupinacci Eric April 25th, 2019 12:33

Ah non, ça c'est sur, pas en fulltext.
Mais est-ce vraiment utile à partir du moment ou on a des catégories plus détaillées et tous les plugins disponibles en recherche (ce qui inclut les champs nom, slogan et description si je me rappelle bien) ?

Maïeul

Maïeul April 25th, 2019 13:03

effectivemet