Gérez votre documentation projet comme du code Raphaël Semeteys - Consultant chez AtoS Publié dans GLMF n°158 – Mars 2013 https://connect.ed-diamond.com/GNU-Linux-Magazine/GLMF-158/Gerez-votre-documentation-projet-comme-du-code
La documentation d'un projet,qu'il soit libre ou non, est encore souvent vue aujourd'hui comme la dernière roue du carrosse : on la gère si on a le temps et en vrai si on en a vraiment envie. Ben oui, on est développeurs et on ne cherche pas forcément à se faire publier chez O'Reilly. Bref on aime écrire, ça oui, mais surtout du code ! Sur mes différents projets, et notamment ceux qui sont libres1 j'ai toujours cherché LE format pivot qui idéalement me permettrait de gérer et de générer mes documents. Naturellement j'ai A adopté L TEX, amoureux du parfait rendu qu'il génère en PDF. Mais bon... il faut quand même être un peu réaliste, ce ne sont pas ni ma copine, ni ma mère, ni mon grand-père qui vont contribuer à la documentation de mon projet dans ces conditions ! Quelles n'ont donc pas étés ma surprise et ma joie lorsque j'ai découvert ce que je vais vous exposer ici : un format pivot lisible par tous et des outils libres pour le manipuler. Ta-dam ! Je vous présente geekettes et geeks... Markdown, Pandoc et Gitit ! Le tuple qui a fait émerger pour moi le concept code <-> edoc.
Pour cela, un grand merci à mon collègue Romain Vimont qui m'a fait une démonstration qui m'a très vite séduit. Et aussi merci à un certain John MacFarlane dont je vais parler plus loin dans cet article. Comme quoi un peu de philo peut changer la donne... (là j'espère vous avoir mis l'eau à la bouche).
Je m'explique... Vous aurez peut-être remarqué que edoc est le palindrome de code (lisez edoc dans le sens droite -> gauche...). Tout ça au final c'est quand même bien lié. Et souvent dans mes projets j'ai regretté que la documentation ne soit gérée pas dans le même système de gestion de
1 cf. http://www.drakkr.org... je fais un peu de réclame ;) version et de partage que le code (quand la supposée documentation existe...). Ben oui plutôt que d'injecter des méta-données dans les noms de document (versions, langues, états... et j'en passe) pourquoi ne pas gérer l'e-document ou l'edoc comme le code (ben oui il me manquait le e pour la permutation parfaite) ?
A Et c'est possible ! Sans faire de L TEX... enfin pas directement ;)
Quand je parle de format pivot j'entends fichier source : comme pour le code, l'edoc doit être écrit dans un langage possédant une syntaxe et devant être compilé pour être lisible par tous dans différents formats. On parle de binaires compilés pour différentes plates-formes, je parle similairement de compilations pour différents formats de lecture.
A Dans la famille des formats pivots, j'ai testé et utilisé : L TEX, DocBook et même OpenDocument (oui, oui c'est du XML zippé après tout). Mais je suis toujours resté sur ma faim et ne voyais toujours pas comment convaincre ma communauté ou mes clients : trop cabalistique, trop verbeux ou trop lié à un outil. Et là... Romain m'a fait découvrir Markdown2. J'ai été très vite impressionné tant le markup (ou balisage) proposé est léger et adapté à une compilation tant par les êtres humains (lecture et écriture) que par les programmes (analyse syntaxique et transformation). Romain m'a aussi et surtout montré Pandoc3, une solution de conversion entre formats de documents, librement développée par John MacFarlane. Et là... je suis carrément entré dans le Condor (respect à ceux qui voient ce à quoi je fais référence, pointeur4 pour les autres). Alors autant dire que quand j'ai découvert que le même MacFarlane avait tout simplement développé un Wiki utilisant Markdown comme format et Git comme backend de stockage et de gestion de versions... je suis rentré dans le Meta-Condor !!! Bref, après ces quelques élucubrations meta-quelquechose, passons à la pratique et à la compilation. Ou autrement dit : "Katia ?! Démonstration !!!".
Un format source léger : Markdown
Bon commencons calmement par la source, l'edoc, et présentons donc les concepts et la syntaxe de Markdown. Markdown5 est à l'origine à la fois une syntaxe légère de balisage de texte et un programme PERL développé entre 2003 et 2004 par John Gruber permettant d'exporter ce format vers XHTML. Depuis, ce format a connu un succès grandissant tant sa syntaxe est facile à lire et à écrire. Et de nombreuses implémentations dans divers langages ou outils ont vues le jour. Malgré l'insistance de la communauté, John Gruber n'a depuis jamais mis à jour le format, ce qui a favorisé l'émergence de plusieurs extensions comme la gestion des tableaux, des notes de bas de pages ou encore des citations.
2 http://daringfireball.net/projects/markdown/ 3 http://johnmacfarlane.net/pandoc/ 4 http://sot.wikia.com/wiki/Sword_of_Truth_Wiki 5 http://daringfireball.net/projects/markdown/ Ces surensembles au format initial partagent tous l'héritage de Markdown et notamment l'avantage d'être très compréhensibles par un humain tout en restant exploitable par une machine via une syntaxe par convention. Markdown est proche en ce sens des syntaxes Wiki, et encore plus de celles couramment utilisées dans les courriels de type texte. En effet la philosophie de base de Markdown, telle que définie par John Gruber est la suivante : Un document formaté selon Markdown devrait pouvoir être publié comme tel, en texte, sans donner l’impression qu’il a été marqué par des balises ou des instructions de formatage.
Illustrons cela avec un simple exemple : # Titre
## Sous-titre
Le texte peut être balisé en _italique_, en __gras__, ~~baré~~, comme du `code`, etc.
Liste :
1. sujet
2. verbe * transitif * intranstitif
3. complément
> Citation avec syntaxe similaire à ce > qui se pratique dans les courriels
Hyperliens simples
 Bref c'est clair, lisible et en même temps simple à utiliser. Et attendez de voir ce que Pandoc peut faire avec ça !
Un translateur très logique : Pandoc
Pandoc est un convertisseur de formats de documentation. Il est développé et maintenu depuis 2006 par un professeur de philosophie de l'université américaine de Berkeley : John MacFarlane6. Il est spécialisé dans l'histoire et la méthodologie de la logique... et il code le soir et le weekend des logiciels GPL en langage Haskell ! Alors je ne fais pas embrayer sur une présentation d'Haskell ni surenchérir sur l'éternel débat des langages de programmation. J'en laisse le bon soin à Jean-Pierre Troll ("J-P, J-P-T revieeeens...").
6 http://johnmacfarlane.net Pandoc7 étend la syntaxe initiale de Markdown pour par exemple y ajouter : La gestion des métadonnées du document % Titre % Auteurs % Date
Le support des tableaux :
Droite Gauche Centre ------12 12 12 123 123 123 1 1 1
Les notes^[Contenu de la note] de bas de page.
La coloration syntaxique de nombreux langages :
~~~ {.Javascript} function AlertError(error) { alert("Erreur : " + error); } ~~~
Une structuration de type slides de présentation... Et j'en passe. Outre ces améliorations et d'autres non présentées ici, la force de Pandoc réside dans le nombre de formats qu'il sait translater ! Je reprend ici la liste officielle des formats supportés à ce jour :
• Pandoc sait lire le format Markdown (que l'on peut considérer comme son format source A et pivot) mais aussi Textile, reStructuredText, HTML, L TEX et DocBook ;
• il sait exporter cela vers texte plein, Markdown, reStructuredText, XHTML, HTML5, A L TEX, ConTeXt, RTF, DocBook, OpenDocument Text, Word docx, GNU Texinfo, WikiText de MediaWiki, EPUB, Textile, pages man de groff, Org-Mode d'Emacs, AsciiDoc ;
A • il sait exporter au format PDF en passant par L TEX ;
• mais il supporte également des formats de slides HTML comme Slidy, Slideous, DZSlides ou encore S5, et si cela ne vous convient pas... il supporte Beamer ! Bref, merci aux deux Johns ! Gruber pour avoir créé une syntaxe extrêmement proche de ce que l'on écrit quasi-naturellement lorsqu'on balise en texte plein. MacFarlane pour cette pierre de rosette informatique. Et il ne s'est pas arrêté à cela le philosophe... Imaginez ce que cela ouvre comme possibilités, et je cite celles qui me viennent à l'esprit lors de la rédaction de cet article :
• translation8 de documentations existantes depuis les formats lus par Pandoc (genre HTML !!) dans le format pivot Markdown, pouvant alors être à nouveau exporté ;
7 http://johnmacfarlane.net/pandoc/ 8 Prenez ce mot comme un mix du mot anglais et de la notion mathématique... et c'est un bon prétexte pour glisser une note de bas de page. • génération automatique de la page man de votre binaire ;
• génération de documents bureautiques, de livres avec la qualité typographique de A L TEX ;
• transformation de votre site Web en SlideShow, en eBook ;
• et je n'ose même pas effleurer les possibilités dans Emacs... ;) Et, bien sur, ces exports sont personnalisables via l'utilisation de templates. Voici juste l'illustration de quelques translations inspirées des exemples introduits plus haut : # edoc
## Exemple d'export Markdown/Pandoc
1. Le texte peut être balisé * en _italique_, en __gras__, * ~~baré~~, comme du `code`, etc^[Marldown/Pandoc supportent de nombreux autres formatages]. 2. Le balisage du texte Hyperliens simples
> Citation avec syntaxe similaire à ce > qui se pratique dans les courriels
Droite Gauche Centre ------12 12 12 123 123 123 1 1 1
Code :
~~~ {.Javascript} function AlertError() { alert(this.error); } ~~~ A Export au format PDF (via L TEX) : Export au format HTML (brut sans CSS) :
Export au format ODT (brut sans template) :
Gérons l'edoc source : Git
Ah mais l'edoc c'est du source comme le code, donc c'est du texte ? Ben oui donc git clone ou git init, git add, git commit, git pull, éventuellement git diff, git merge et finalement git push !!!
Donc ça y est, là on gère enfin le code et l'edoc de la même manière, avec les mêmes outils. Par exemple : raph@osc-rss:~/Documents/RSS/Articles/edoc$ git status # On branch master # Changes not staged for commit: # (use "git add/rm
## Exemple d'export Markdown/Pandoc @@ -9,6 +12,8 @@
+Illustration des caractères en indices et exposants : L^A^T~E~X. + > Citation avec syntaxe similaire à ce > qui se pratique dans les courriels Ou des logs du type : raph@osc-rss:~/Documents/RSS/Articles/edoc$ git log commit bacc47040f0487c2dd75d7cdc4f92a6802c3dc7b Author: Raph
Classe PHP pour edoc et documentation associée. commit 9f1ed86029c21049d576d231b7a2b0bf640b0566 Author: Raph
Exemple géré en version commit 64ec3a04dd57d5d1abcaeac76b3f976d6ee6432e Author: Raph
Init
Le code et l'edoc sont donc des objets similaire gérés au niveau de projet de la même manière.
Un Wiki qui vous veut du bien : Gitit
Vous aurez peut-être remarqué qu'un des formats d'export supporté par Pandoc est la syntaxe de MediaWiki (WikiText). Cela est très intéressant car cela permet d'envisager une convergence entre un document bureautique et un document collaboratif de type Wiki, en conservant un edoc unique comme source et format pivot. Et que croyez-vous que MacFarlane a fait ? Ben il a aussi codé un Wiki, Gitit9, qui utilise Markdown/Pandoc comme syntaxe et surtout Git comme backend. Donc je peux mettre à jour indifféremment mon site ET mon edoc via un git push OU via le Wiki Gitit !!! Là cela commence à franchement être génial. La bureautique et le Web ne sont que des formats de diffusion et de consultation de votre edoc, que vous pouvez gérer de manière collaborative soit à la méthode Geek (donc via Git), soit à la méthode plus Web (donc via Gitit).
9 http://gitit.net En effet, lorsque une page du Wiki est modifiée via le Web, le source Markdown/Pandoc est automatiquement mis à jour via un git commit dans le dépôt Git associé au Wiki Outre un logo amusant (et un jeu de mot... bon, un jeu de mot quoi : Gitit... Get It!) et une feuille de style CSS largement inspirée de celle de MediaWiki, Gitit présente l'intérêt de justement utiliser Pandoc pour gérer l'export des pages Wiki dans les multiples formats supportés. On reste donc résolument dans l'écosystème Haskell, avec notamment l'utilisation du serveur d'application HappStack10 (ou Haskell Application Stack). Illustrons la force de cette solution mixte Wiki/Git via un exemple de mise à jour d'une page Gitit existante :
Modifions le code source de la page via vi, puis passons à git :
10 http://www.happstack.com raph@osc-rss:~/wikidata$ git status # On branch master # Changes not staged for commit: # (use "git add
edoc modifié pour l'example
Vérifions maintenant l'historique de l'edoc en question via le Wiki :
Bref, du bonheur. Outre la syntaxe Markdown/pandoc, Gitit permet également la gestion de méta-données spécifiques au mode Wiki, à impérativement positionner en tout début de edocdans un bloc délimité par --- et ... : --- categories: catégories associées à la page toc: [true|false] affichage ou non de la table des matières title: titre long optionnel de la page (qui écrase son titre technique) ... Gitit permet bien évidemment de gérer des liens internes entre pages du Wiki : [Texte à afficher](Nom interne de la page à lier) Ordonnançons un peu tout ça : make
Tout comme pour le code, il est utile d'organiser et d'automatiser l'export des documents via un mécanisme de build. J'ai choisi pour cet article d'utiliser GNU make : all: doc-odt doc-pdf doc-html doc-odt: pandoc --toc -o edoc.odt edoc.md doc-pdf: pandoc -o edoc.pdf edoc.md doc-html: pandoc --self-contained -o edoc.html edoc.md Cet exemple simpliste se contente d'exporter l'article que vous lisez aux formats ODT, PDF et HTML. Mais je suis certain que vous êtes déjà en train d'imaginer des builds tordus à base de variables, de commandes git et d'options de personnalisation de pandoc. Précisons également que ceci peut être réalisé par tout autre mécanisme de build (comme CMake, Ant, Maven, Rake, Phing, etc.) et de préférence celui déjà utilisé pour construire les binaires de votre projet.
Conclusion
Histoire de bien enfoncer le clou, synthétisons les similitudes entre le code et l'edoc :
• le source est compilé et cette étape peut être automatisée voire faire partie du cycle d'intégration continue du projet (pour pouvoir éventuellement refuser une contribution qui ne serait pas assez documentée) ;
• on utilise un langage doté d'une syntaxe partagée par les humains et les machines ;
• il est possible d'ajouter des commentaires réservés aux humains et donc non traités lors de la compilation ;
• le source peut être géré en versions et faire l'objet de travail collaboratif et de revue par les pairs ;
• les différentes versions du source peuvent être comparées et la gestion de leurs évolutions et des potentiels conflits s'en trouve grandement facilitée (par exemple via diff et autres Kdiff ou Meld). Bref, lorsqu'en plus on ajoute à tout cela la possibilité d'indifféremment modifier le source via un éditeur de texte ou via le wiki, j'ai envie de dire : "Bienvenue dans la Documentation 2.0..." (Yes, Bingo!). Soyons fous, allons plus loin !!!
Bon on a vu que Markdown et Pandoc permettent de facilement intégrer du code dans de l'edoc, en gérant notamment la coloration syntaxique.
Pourquoi ne ferions-nous pas aussi l'inverse ? Intégrons de l'edoc dans le code ! Et ainsi, plutôt que de générer de la Javadoc ou autres variantes, générons du générique. Capable d'être exporté dans nos wikis, en PDF, en ODT, via RSS, comme NetBooks !!!
Ben oui, l'ère de l'edoc a commencée ! Bon OK là j'ai définitivement gagné au Bingo!, mais l'idée de base mérite tout de même réflexion et surtout, AMHA, implémentations...
Et au final pourquoi pas des articles GNU/Linux Magazine France directement composés en edoc ? Ca faciliterait leur export vers http://www.unixgarden.com...
Remerciements
• R@main Vimont : qui m'a pointé vers Markdown et Pandoc.
• Linus Torvald : après avoir révolutionné le monde des systèmes d'exploitation, il a juste tout bonnement codé Git... parce qu'il était énervé !
• John MacFarlane : It's logical, innit?
• John Gruber : les idées les plus fortes sont parfois les plus simples.
PS : l'edoc de cet article a bien évidemment été écrit en Markdown puis compilé par Pandoc, géré en version par Git/Gitit et sera plus tard publiquement propulsé par Gitit.