Actuellement, mes plugins sont sur des repo Github avec:
La doc dans repo/plugin/docs/fr_FR
Les screenshots qui s’affichent sur le market dans repo/plugin/docs/images (plugin_screenshotx.jpg)
Tout fonctionne sauf qu’à chaque fois que je veux updater ou juste corriger une faute d’orthographe sur la doc, une nouvelle version du plugin est créée.
J’ai donc crée un repo jeedom_docs avec dedans juste la doc des plugins, et je compte updater mes plugin_info/info.json pour rediriger leurs docs vers ce repo.
Ce qui me permettra alors d’updater les changelogs et docs comme je veux, sans générer une nouvelle version du plugin et donc une mise à jour (pour rien) chez chaque utilisateur.
Juste j’ai bon ?
Mais, où dois-je mettre les fichiers plugin_screenshotx.jpg ? Est-ce qu’ils doivent forcément être dans le repo/plugin/docs/images ? Et donc, nouvelle version à chaque fois que j’update un screenshot ? Ce qui n’est pas un drame, puisque nouveau screenshot veux à priori dire nouvelle fonction donc nouvelle version.
Mais ce serait encore plus souple d’avoir les screenshots du market dans mon repo de docs, est-ce faisable ?
Bonjour,
Je crois bien qu’il n’y a personne…
Je suis intéressé par ta solution.
Si j’ai bien compris tu as un repo avec uniquement les docs, la génération des docs est faite sur ce repo et la traduction aussi ?
Comment y parviens tu ?
Désolé, je gère mes docs de mon coté, jamais compris comment générer la doc et les traductions de manière fiable, plein d’infos contradictoires et de problèmes remontés sur le forum.
Et vue le nombre de plugins avec des liens documentations et changelog en 404, même des plugins conseillé, je préfère gérer çà.
Du coup je suis passé sur les pages github, c’est propre, j’ai réussi a mettre des popups sur les images, donc pas envie de risquer de tout casser.
Si les screenshots pouvaient suivre le lien de doc dans le dossier /images, ce serait super. Si ils doivent rester dans le repo du plugin, tant pis je ferai avec. Le top je pense serait même de les uploader directement depuis le market, mes creations/plugin/editer.
je me pose le même genre de question maintenant que github vient d’autoriser les repo privés (3 collaborateurs, mais pas de « Pages » dispo) en mode gratuit.
dans le cas ou on fait un repo pour les docs, les plugins doivent-ils toujours contenir la doc dans /docs (la doc locale est-elle toujours d’actualité (en failover ?)?)
Je suis tombé sur le plugin MySensor de Lunarok et je ne comprends pas tout
Le plugin sur le market renvoi sur la doc de son github de docs, ok.
Ses screenshots sont sur le github du plugin dans doc/images/ et pas sur son repo de docs. Je vais donc suivre la même logique.
Par contre:
Les mêmes screenshots et images sont aussi sur le repo du plugin dans /plugin_info
Le repo du plugin possède une doc au format asciidoc, mais sur la page de documentation jeedom quand on clic sur le lien mysensor, c’est la doc perso de Lunarok qui apparrait et pas l’asciidoc. Je ne savais pas çà possible et du coup çà m’interesserai d’avoir mes plugins en lien sur la page de jeedom https://jeedom.github.io/documentation/#plugin qui renvoi vers mes propres docs
la partie asciidoc à mon avis c’est juste un zombie de l’ancien format doc qu’il n’aurait pas supprimé, mais ca pourrait toujours être utilisé pour une doc locale dans le cas d’une jeedom non connectée ?
concernant la doc générale, ca se fait tout seul normalement, mais la moulinette a déjà eu des ratés… peut-etre voir au cas par cas avec Loic
la doc : user/jeedom_docs/plugins/monplugin/fr_FR/index.md
le changelog : user/jeedom_docs/plugins/monplugin/fr_FR/ changelog.md
les images dans user/jeedom_docs/plugins/monplugin/images/
Pour l’icone du plugin je la laisse sur le repo du plugin puisque que jeedom et le market en on besoin. Et je la duplique sur mon repo jeedom_docs si besoin dans la doc.
Libre à toi ensuite sur ton repo jeedom_docs d’activer les pages github
Non, aucune génération automatique, traduction etc, je ne veux pas tout casser.
J’ai un plugin assez simple, je vais voir pour générer le i18n à la mano pour l’interface du plugin.
Pour l’autre, Qivivo, c’est un produit purement français.
J’ai pas envie de révolutionner les doc Jeedom, qu’on soit d’accord. J’avais juste envie de proposer une doc plus pro et propre qu’un readme sur github, et de pouvoir la mettre à jour sans générer une mise à jour du plugin sur toutes les installations. C’est tout
Bonjour,
Personnellement, Je ne vois pas en quoi c’est gênant de mettre à jour le plugin pour une maj de doc:
Du moment que le changelog l’indique;
Si seul la doc est modifiée, il n’y a pas de risques de régression.
Avoir la doc dans le même repo que le code a aussi des avantages. Ça permet sur le même commit de mettre à jour la doc, ce qui participe à la description/comprehension du commit.
screenshot dans plugin_info avec id_screenshot.png, id_screenshot1.png …
→ ca le market est content avec et les ajoute, mais ca sert pas en doc (pour la doc, j’évite au maximum les screenshots, pour éviter une maintenance en cas de màj de jeedom, c’est ce que fait loic aussi)
lien doc et changelog dans le info.json
→ ca marche depuis jeedom
→ ca marche depuis le market le bouton doc
----> ca ne marche pas pour l’ajout dans jeedom.com/documentation (loic a répondu sur ce point qu’il fallait donner à son utilisateur les droits de lecture/ecriture sur le repo, meme si on ne gère pas la traduction par exemple et que les dépots sont privés)
documentation de tous les plugins dans un repo séparé, pourquoi ?
1 - un seul thème à maintenir
2 - je gère ma documentation séparément du code et comme ca je n’ai pas d’obligation à pousser une maj du plugin pour simplement publier une correction d’orthographe ou une FAQ additionnelle
Par contre j’ai pas de traduction de cette doc du coup, c’est surtout qu’aujourd’hui j’ai pas du tout regarder ce point
Merci Lunarok, tu confirme ce que j’ai mis en place, et on a le même point de vue.
J’ai un plugin avec plus de 600 installations, je vais pas faire ch… 600 personnes avec des messages de mise à jour, qui vont se demander pourquoi, allez voir le changelog etc etc pour … une faute d’orthographe !
Et avec jekyll, toute la config de mes doc est au même endroit, un seul css, js etc pour toutes les pages. Beaucoup plus pratique.
