Génération De Documentation (automatique) - 2016-04-06

Hyacinthe Hyacinthe : ton outils d'extraction automatique de documentation à partir des sources me semble être la bonne voie. J'avais glâné quelques ressources :

• Static Site Generators : une synthèse des outils GPP 2.23 — Generic Preprocessor : je savait même pas que ça existait. A creuser ;-) Building Publishing Workflows with Pandoc and Git HF Antennas: Vertical or Horizontal? : Un exemple de site statique (pas beau) >>> ouvrir le fichier "make" : lien en haut à gauche. Writing, Markdown and Pandoc Pandoc Extras : d'autres outils EspruinoDocs : sous /bin, je générateur de doc.

Hyacinthe - 2016-04-06 at 9:07 AM

Merci Hyacinthe Hyacinthe comme vous avez commencé à avancer ce sujet à proposer un draft de solution à la réunion de Lundi prochain. Ça vous va ?

Hyacinthe - 2016-04-06 at 10:38 AM

Ca dépendra de l'avancement. C'est en train de murir tranquillement. Mais je pourrais dire deux mots de la voie qu'on est en train d'explorer.

Hyacinthe - 2016-04-06 at 10:43 AM

+1 :) Pour voir en pratique, cf dernières modifications sur le wiki.

Hyacinthe - 2016-04-06 at 11:50 AM

C'est plutôt bien je trouve.

Hyacinthe - 2016-04-06 at 2:53 PM

Wep ça marche pas mal. Shell+pandoc+bot wiki en python :)

Hyacinthe - 2016-04-06 at 4:17 PM

Le Shell aura un peu de mal à tourner sous Windows, mais comme tu vas nous scripter tout ça en Python on sera bien multiplateforme ;-).

Hyacinthe - 2016-04-07 at 8:21 AM

Dans ce cadre et aussi en rapport avec https://3.basecamp.com/3152267/buckets/155345/messages/100695652. Je pense qu'il est temps de commencer à mettre en place un système de référencement cohérent des entités manipulées et que l'on retrouvera un peu partout (doc, dépot, sources, noms de fichier, de répertoires, URL...). Je propose, surtout histoire de lancer débat, quelque chose comme :

• Composants (CMP-...) : CMP-alimentation CMP-HValim (se forkant par exempe, en CMP-HV_alim_cascaded ou CMP-HV_alim_boost, CMP-HV_alim_hv7360...) CMP-tranducer_ENS_v2 ... et n'importe quoi commençant par CMP-... Signaux d'interface (SIG-... ou ITF-...) : SIG-gnd SIG-5v SIG-pulse_HV SIG-amplified_signal **Fonctions (FCT...)* : FCT-sensing FCT-... Et tout ce qu'on veut ...

  Bon, vous avez compris le principe. C'est ce système de référencement qui sera garant de l'intégrité du projet et nous permettra d'en automatiser au maximum la gestion. C'est, par exemple ce qu'on retrouvera en métadonnées des éléments de documentation. Mais pourquoi pas, aussi, directement dans les commentaires des sources. Ce référentiel sera le degré 0 de l'echOsystem. Avec ça, plus d'ambiguité entre FCT-clipping et CMP-clipper. On peut référencer à peu près tout : exemple un Captech (CAP-tech_2016-04-05) ce qui permettra de le siter dans, par exemple, l'argumentation d'une technologie décrite dans la doc d'un composant et donc naviguer du composant au notes du Captech.

Hyacinthe - 2016-04-12 at 6:20 AM

Hyacinthe Hyacinthe par rapport à ce qui a été dit hier, pensez-vous qu'il serait intéressant de créer un repo GitHub pour tester le modèle discuté de documentation ?

1. Créer un repo sur le Github "medico-technique" 2. Ajouter un readme avec l'essentiel des règles (que nous pourrons modifier au fur et à mesure) incluant : 1. How to contribute 2. File name (nomenclature) 3. Principles / flow and merge conditions 4. Glossaire (inclu ou non dans le readme) - fait par Hyacinthe 3. Ajouter le premier module (réalisé par Michel) avec doc & source files puis avancer avec Hyacinthe sur les autres modules petit à petit et voir comment ajuster ? On pourrait ainsi faire un bilan à chaque ajout et ajuster l'ensemble en conséquence.

   L'idée serait de pouvoir avoir en un seul endroit tous nos derniers éléments qui convergent et qui ainsi nous permettrons de tester les hypothèses d'organisation de la documentation. Ce sera aussi une bonne occasion de tester les issues, notamment avec la question posé hier par Jean sur l'ADC et d'en discuter directement sur github. Dès qu'on ajoute un contenu on peut ensuite supprimer les google doc correspondants. Vos avis et remarques ?

Hyacinthe - 2016-04-12 at 7:35 AM

Ok d'ac, laissez moi juste un peu de temps pour essayer de créer une base la plus cohérente possible. Ou alors je fork chez moi et fait un pull request ensuite. "Ce sera aussi une bonne occasion de tester les issues, notamment avec la question posé hier par Jean sur l'ADC et d'en discuter directement sur github." : Peut-être pas la peine dans un premier temps de tous basculer sur GitHub. D'abord voir si on peut faire un bon dépot pour y mettre ce qui est stable. Et en retirer de la doc à jour. On peut aussi en faire un "brouillon" pour essayer d'y faire tenir tout l'existant afin de voir si la structure est "bullet proof" et ensuite on en refait un tout propre avec uniquement la nouvelle génération modulaire.

Hyacinthe - 2016-04-12 at 7:38 AM

Top. J'ai créé le repo, @Hyacinthe tu en es admin également, comme ca tu pourras aussi aider à gérer les pull-requests pertinentes ;) Tu peux forker!

Hyacinthe - 2016-04-12 at 9:38 AM

ok. top. Do it, fail it fix it ;) Hyacinthe Hyacinthe on te laisse le temps de voir et dès qu'on a ton feu vert, on tenter d'ajouter le module de michel pour test. On pourra en effet tout à fait le refaire ensuite après avoir tester. Merci.

Hyacinthe - 2016-04-12 at 12:27 PM

( dans l'esprit : <http://www.koszek.com/blog/2016/04/11/dont-document- automate/> )

Hyacinthe - 2016-08-19 at 11:22 AM

ce n'est pas de la doc automatique mais il s'agit de la structuration sous le format GitBook que j'évoquais la semaine prochaine et que je ré-évoquerais en réu qd tout le mode sera là on a 4 GitBooks en chantiers - espace echOpen - start-kit : instance echOpen - l'application android - l'image processing l'avantage - structuration de la doc via un plan >> wiki - édition collaborative - synchronisation bi-directionnelle GitBook <-> GitHub & donc congruent à la génération de doc

Hyacinthe - 2016-08-19 at 11:26 AM

J'ajouterais que la génération de doc peut aussi générer un gitbook, easy. Pour harmoniser les structures de gitbook, il peut être intéressant d'avoir une table des matières générale commune à ces gitbook, pour avoir de la cohérence entre les travaux.

Hyacinthe - 2016-08-19 at 11:40 AM

yep pour l'autodoc btw, je suis déjà dessus sur les communs de doc : non seulement sur le plan mais aussi les licences, les formats de biblio & such. Un sujet à traiter es l'update de l'information. Suggestion : toutes les informations dont on sait qu'elles sont sujettes à évoluer doivent avoir un sigle distinctif, ce qui permet de les retrouver par search et d'ajuster ~un peu comme les @todo dans les IDE j'ajouterai aussi qu'on peut les assembler et les vendre ;)

Hyacinthe - 2016-08-19 at 12:01 PM

du coup il faut qu'on fasse un point sur - l'harmonisation du soft et du modèle de doc de Hyacinthe Hyacinthe - la génération de gitbook à partir de l a doc -> mini-workshop sur la doc vendredi prochain ? en mode reprise de saison pour les apéros

Hyacinthe - 2016-10-17 at 9:20 PM

A y est, le PDF généré dépasse les 250 pages sur le kit, quand on le DL en PDF =)