Gérez votre documentation projet comme du code

GNU/Linux Magazine n° 158 | mars 2013 | Raphaël Semeteys
Creative Commons
  • Actuellement 0 sur 5 étoiles
0
Merci d'avoir participé !
Vous avez déjà noté cette page, vous ne pouvez la noter qu'une fois !
Votre note a été changée, merci de votre participation !
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 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 :

# 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 <http://www.url.org> ou [avec un titre](http://fsf.org).

![Texte alternatif](edoc.png "Titre")

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 :

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

# 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 <http://www.url.org> ou [avec un titre](http://fsf.org).

![Texte alternatif](edoc.png)

> 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);

}

~~~

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 :

raph@osc-rss:~/Documents/RSS/Articles/edoc$ git status

# On branch master

# Changes not staged for commit:

#   (use "git add/rm <file>..." to update what will be committed)

#   (use "git checkout -- <file>..." to discard changes in working directory)

#

#       modified:   exemple.md

#       deleted:    exemple2.md

#

# Untracked files:

#   (use "git add <file>..." to include in what will be committed)

#

#       edoc.class.php

no changes added to commit (use "git add" and/or "git commit -a")

et donc :

raph@osc-rss:~/Documents/RSS/Articles/edoc$ git diff exemple.md

diff --git a/exemple.md b/exemple.md

index a1ca33a..d26e50b 100644

--- a/exemple.md

+++ b/exemple.md

@@ -1,3 +1,6 @@

+% Exemples edoc

+% Raphaël Semeteys

+

# edoc

## Exemple d'export Markdown/Pandoc

@@ -9,6 +12,8 @@

![Texte alternatif](edoc.png)

+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 <raphael.semeteys@atos.net>

Date:   Wed Jan 16 14:33:36 2013 +0100

    Classe PHP pour edoc et documentation associée.

commit 9f1ed86029c21049d576d231b7a2b0bf640b0566

Author: Raph <raphael.semeteys@atos.net>

Date:   Wed Jan 16 14:32:43 2013 +0100

    Exemple géré en version

commit 64ec3a04dd57d5d1abcaeac76b3f976d6ee6432e

Author: Raph <raphael.semeteys@atos.net>

Date:   Wed Jan 16 14:26:43 2013 +0100

    Init

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 :

raph@osc-rss:~/wikidata$ git status

# On branch master

# Changes not staged for commit:

#   (use "git add <file>..." to update what will be committed)

#   (use "git checkout -- <file>..." to discard changes in working directory)

#

#       modified:   edoc.page

#

no changes added to commit (use "git add" and/or "git commit -a")

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

raph@osc-rss:~/wikidata$ git add edoc.page

raph@osc-rss:~/wikidata$ git commit -am"edoc modifié pour l'example"

[master 971d345] edoc modifié pour l'example

1 file changed, 1 insertion(+), 4 deletions(-)

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

raph@osc-rss:~/wikidata$ git log

commit 971d345182ac8153464326b7a2309372208fe548

Author: Raph <raphael.semeteys@atosorigin.com>

Date:   Wed Jan 16 15:52:10 2013 +0100

    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étadonnées spécifiques au mode Wiki, à impérativement positionner en tout début de edoc dans 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)

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 :

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é ! 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 ;)]