Groupe de documentation

[toregreb]

Bonjour,

Je suis en train de finaliser la documentation du plugin thermostat.
Ne serait-il pas possible d'avoir un niveau 2 dans la table des matières en haut à gauche du document ?

[marie]

J'ai demandé à Loïc déjà mais il a des soucis lorsqu'il l'implémente...
Merci pour la doc

[toregreb]

OK, pas de souci.

[toregreb]

Je viens de faire un pull request de la documentation du plugin thermostat.

[chamalo]

Donc comme la fait remarquer loic c'est le bootstrap backend qui est utilisé, et il possède certaines subtilités propre a bootstrap, j'avais fait un petit tuto sur ce post : https://forum.jeedom.fr/viewtopic.php?f ... 6&start=40

je le remets ici :

On a la possibilité d'utiliser toute les class bootstrap pour ça il suffit de le préciser dans un attribut role

Code : Tout sélectionner

{role="text-justify"]
--
blabla
--

Dans ce cas la classe text-justify va s'appliquer à l'open Block (--) ( un open block correspond a un paragraphe)
dans la même optique on peut utiliser la classe col-md-* ( remplacer * par la taille que vous voulez de 1 à 12 ) pour faire du multi-colonne, si vous utilisez le multi-colonne pensez bien à délimiter vos paragraphes avec des open block
Si vous faites du multi-colonne penser à rajouter le code ci-dessous avant chaque titre de section, cela permet de réinitialiser le multi-colonne :

Code : Tout sélectionner

[role="row"]

on a souvent besoin de rajouter une ligne vide

Code : Tout sélectionner

{nbsp} +

si vous voulez utiliser les Admonitions blocks(paragraphe délimité par un cadre) avec des images( TIP, IMPORTANT ...etc... ) il faudra rajouter dans le fichier index.asciidoc

Code : Tout sélectionner

:icons:

et il faudra rajouter avant le block:

Code : Tout sélectionner

[icon="../images/tip.png]
[TIP]

pensez à d'abord télécharger vos icônes dans votre répertoire images

ci dessous un Admonition block, justifié qui prend tout l’écran avec un icône

Code : Tout sélectionner

[role="col-md-12 text-justify"]
--
[icon="../images/important.png]
[IMPORTANT]
blablabla
--

En attendant la V4.4.0 du backend, les images dans un texte ne s'affiche pas correctement, elle s'affiche comme un block pour palier à ça rajouter une classe à votre image:

Code : Tout sélectionner

image:MonImage[role="img-thumbnail"]

comme je le dit dans l'autre post, il ne sert à rien de tester vos fichiers asciidoc sur les divers site de test, seul une conversion manuel par votre Jeedom vous donnera un rendu fidèle, au premier abord cela paraît compliqué mais on une fois qu'on a compris cela va très vite et l'écriture devient naturel

[toregreb]

Merci Chamalo pour toutes ces précisions, j'avoue m'être posé beaucoup de questions quant à la mise en forme et le rendu de mon document. C'est tout naturellement que j'ai lu de long en large la documentation du plugin thèmes, qui a du te demander un très gros travail (vu la quantité d'images et le nombre de styles différents utilisés).
Je vais surement être amené à retoucher la documentation du plugin thermostat après la publication.

Questions :

• Qu'entends tu par conversion manuel par votre Jeedom ? Est-ce la publication sur le site de doc de Jeedom ?
• j'ai utilisé pas mal d'admonition block, je trouve cela très pratique pour mettre en avant un point important. Est-ce que des icônes par défaut existent ou faut-il faire obligatoirement comme tu le dis, copier les icones ? Ou peut-on trouver ces icônes si besoin ?

Remarques :
Concernant la doc du plugin thèmes, j'ai vu que tu mettais souvent image et texte côte à côte, mais ne peut-il pas y avoir des différences entre navigateur car moi, dans Chrome, j'ai ça :

Chevauchement dans doc thèmes

thèmes_chevauchement.png (31.12 Kio) Consulté 2396 fois

Enfin, je comprends que le boulot que tu as accompli, tant pour le plugin que pour sa doc soit considérable, et tu as du répondre à de nombreuses questions dont les réponses se trouvent dans la doc mais cette FAQ m'a fait sourire au début. Et je me demande maintenant si elle est vraiment utile dans une documentation :

FAQ de la documentation du plugin Thèmes

Documentation_themes.png (3.86 Kio) Consulté 2396 fois

C'est peut-être pour voir si on lit ta documentation.....

[chamalo]

pour la conversion oui cela correspond à le faire manuellement à partir de Jeedom en se connectant en SSH, voici la commande à taper:

Code : Tout sélectionner

asciidoc -b bootstrap -a numbered -a responsive-option -a navbar=fixed -a brand="Jeedom test" -a jumbotron-fullwidth -a toc2 -a footer-fullwidth -a toclevels=1 -a tocaffix -o path/MON PLUGIN.html /usr/share/nginx/www/jeedom/plugins/MON PLUGIN/doc/fr_FR/index.asciidoc

en remplaçant MON PLUGIN par votre plugin, path étant le répertoire de destination, soit vous utilisez /var/www/doc.jeedom.fr/fr_FR/ et pour voir le résultat vous passez par la Doc sur www.jeedom.fr soit vous donnez un répertoire locale pour vérifier le résultat et dans ce cas il faut reproduire arborescence avec le répertoire fr_Fr et images

Non il n'y pas d’icônes par défaut il faut les télécharger manuellement dans ton répertoire images le plus simple étant de télécharger ceux fournit dans la documentation asciidoc : http://powerman.name/doc/asciidoc

le problème de l'image est simple , j'ai prévu un colonage de col-md-4 ,col-md-8, 4 pour les images , 8 pour le texte et dans ce cas 4 ne suffit pas, il faudrait que je soit à 6-6

T'inquiète je devrait compléter la FAQ une fois que la nouvelle version stable sera disponible, mais pour l'instant il y a encore beaucoup de modifications qui vont être apporté, et personnellement je pense que même si je l'ai fait avec beaucoup d'humour, certain devrait prendre ce conseil au pied de la lettre et quelque soit la question

[SBO]

J'ai cherché un éditeur Asccidoc qui rend conforme le rendu mais sans succès. Même avec Atom et le module Asciidoc le rendu n'est pas fidèle.

AsciiDoc est bien pour faire des documents avec peu de mise en forme, après c'est vite prise de tête

J'ai le même pb de toregreb de chevauchement, en dezoomant cela passe, mais doc moins lisible.

[chamalo]

au niveau de la doc Thèmes ce n'est qu'un problème de colonage je suis passé en 5-7 et il n'y a plus de chevauchement par contre je ne publierais pas en l'état j'ai des modifications en cours sur le plugin qui ne peuvent pas être publier je doit finir le débug

[toregreb]

Merci pour toutes ces précisions, je vais donc installer asciidoc dans jeedom pour être au plus près du rendu final.

Mais il serait quand même intéressant d'avoir un endroit pour visualiser le rendu avant publication, ça éviterait des merges successifs car comme vous l'avez dit, ni github, ni les extensions chrome ou firefox ne sont parfaitement fidèles à partir du moment où la documentation est un peu stylée. J'ai relu certaines docs ce matin et je me suis aperçu de quelques coquilles de mise en forme qu'il va bien falloir corriger.

[chamalo]

@loic, pense tu qu'il serait possible de rajouter un bouton 'Voir la Doc en locale' à coté d'Envoyer sur le market qui s'affiche seulement si le fichier 'Mon Plugin.html' existe dans le repertoire fr_FR, cela permettrai de générer la doc à partir de notre Jeedom et facilement la visualiser sans avoir à l'envoyer sur le market, il faudrait toujours installer asciidoc en local on se retrouverai avec une ligne de commande de se type :

Code : Tout sélectionner

asciidoc -b bootstrap -a numbered -a responsive-option -a navbar=fixed -a brand="Jeedom test" -a jumbotron-fullwidth -a toc2 -a footer-fullwidth -a toclevels=1 -a tocaffix -o/usr/share/nginx/www/jeedom/plugins/MON PLUGIN/doc/fr_FR/MON PLUGIN.html /usr/share/nginx/www/jeedom/plugins/MON PLUGIN/doc/fr_FR/index.asciidoc

[loic]

Je suis moyennement pour ce genre de chose car quand je mets a jour le backend, en plus je le modifie de temps en temps le résultat peut encore différer, en plus la on commence a avoir pas mal d'exemple...

[abarrau]

Bonjour,
Est-ce que vous avez déjà essayé de faire des tableaux avec cette "version" de asciidoc ?
Car perso, j'y arrive pas ...
Je veux bien un exemple de code si qqun a fait !
Merci,

[marie]

J'y suis arrivée en regardant un site mais j'ai plus le nom en tête... Mais ça rendait pas terrible et impossible de faire afficher les lignes...

Mais en gros il fallait écrire :
== (en début et fin de tableau)
Et faire :
| ce que tu veux dans colonne 1|en colonne 2 etc et sauter une ligne quand tu passais à la ligne suivante

[abarrau]

Merci Marie, oui comme moi quoi ...
(c'est que je voulais dire "j'arrive pas à faire un beau truc")

les lignes n'apparaissent pas et je trouve qu'au final le rendu est pas top ...
Pourtant des tableaux pour certains cas, ça permet de cadrer les choses contrairement aux puces !
(bon je continue de chercher au cas où)

[marie]

Ouaip je suis d'accord mais du coup j'étais passé aux puces je crois avec des flèches stylisées

[chamalo]

je viens de faire des petits tests avec comme départ l'exemple 1 de table : http://powerman.name/doc/asciidoc
par contre pour être en conformité avec bootstrap je lui est appliqué une classe table bootstrap : http://getbootstrap.com/css/#tables

Code : Tout sélectionner

[options="header,footer",role="col-sm-12 table"]
|=======================
|Col 1|Col 2      |Col 3
|1    |Item 1     |a
|2    |Item 2     |b
|3    |Item 3     |c
|6    |Three items|d
|=======================

on voit bien dans role la classe col-sm-12 qui dit de prendre 12 colonne sur la page et d'appliquer la class table de tableau
voici le résultat :

table.png (4.88 Kio) Consulté 2301 fois

Donc ne pas oublier que c'est le backend-bootstrap qui finalise la visualisation, pour tout objets spécifique existant dans bootstrap il faudra les associer à leur classe respective

[abarrau]

Donc ne pas oublier que c'est le backend-bootstrap qui finalise la visualisation, pour tout objets spécifique existant dans bootstrap il faudra les associer à leur classe respective

Oui oui c'est bien là le problème; car avec le plugin Chrome, j'ai pas le mm résultat que ce qui sort au final ... (point déjà abordé par toi et d'autre plus haut dans le post).
Je vais essayer avec ton exemple.

Est-ce que tu as trouvé une "doc" liée au bootstrap ?

[chamalo]

la doc officiel : http://laurent-laville.org/asciidoc/boo ... index.html

@loic le backend est passé en 4.4.0 à toi de voir si cela n'a pas trop d'impact

[loic]

On est deja en 4.4.0