Gérez votre documentation projet comme du code

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 adopté LATEX, 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 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é 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 pas gérée dans le même système de gestion de version et de partage que le code (quand la supposée documentation existe...). Ben oui, plutôt que d'injecter des métadonné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) ?

Et c'est possible ! Sans faire de LATEX... 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 plateformes, je parle similairement de compilations pour différents formats de lecture.

Dans la famille des formats pivots, j'ai testé et utilisé : LATEX, 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 !!! ».

1. Un format source léger : Markdown

Bon, commençons 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 vu 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.

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 exploitables 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 :

Bref, c'est clair, lisible et en même temps simple à utiliser. Et attendez de voir ce que Pandoc peut faire avec ça !

2. 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 week-end des logiciels GPL en langage Haskell !

Alors je ne vais 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... »).

Pandoc7 étend la syntaxe initiale de Markdown pour par exemple y ajouter :

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 reprends 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 et pivot), mais aussi Textile, reStructuredText, HTML, LATEX et DocBook.
• Il sait exporter cela vers texte plein, Markdown, reStructuredText, XHTML, HTML5, LATEX, ConTeXt, RTF, DocBook, OpenDocument Text, Word docx, GNU Texinfo, WikiText de MediaWiki, EPUB, Textile, pages man de groff, Org-Mode d'Emacs, AsciiDoc.
• Il sait exporter au format PDF en passant par LATEX.
• 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 John ! 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é ;
• génération automatique de la page man de votre binaire ;
• génération de documents bureautiques, de livres avec la qualité typographique de LATEX ;
• transformation de votre site web en SlideShow, en eBook ;
• et je n'ose même pas effleurer les possibilités dans Emacs... ;)

Et, bien sûr, ces exports sont personnalisables via l'utilisation de templates.

Voici juste l'illustration de quelques translations inspirées des exemples introduits plus haut :

Export au format PDF (via LATEX) :

Export au format HTML (brut sans CSS) :

Export au format ODT (brut sans template) :

3. 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 :

et donc :

ou des logs du type :

Le code et l'edoc sont donc des objets similaires gérés au niveau de projet de la même manière.

4. 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).

En effet, lorsqu'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 mots... bon, un jeu de mots 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 :

Ajoutons-la au dépôt de Gitit :

Vérifions la log du dépôt :

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étadonnées spécifiques au mode Wiki, à impérativement positionner en tout début de edoc dans un bloc délimité par --- et ... :

Gitit permet bien évidemment de gérer des liens internes entre pages du Wiki :

5. 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 :

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é ! 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 ? Ça faciliterait leur export vers http://www.unixgarden.com... [NDLR : et ça compliquerait grandement le flux d'édition qui est orienté « papier » ]

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. [NDLR : et qui a été repris manuellement afin de pouvoir intégrer le process de mise en page ;)]