Ainsi, on remarque bien souvent deux types de documentation mutuellement exclusifs :

  • documentation dans un wiki : c'est pratique pour tout utilisateur. Chacun peut contribuer et faire évoluer la documentation. Mais aucun de ces wikis ne permettent, à ma connaissance, l'export de toutes les pages écrites dans un autre format, comme PDF pour pouvoir l'imprimer, ou même un simple export HTML pour consultation hors-ligne.
  • documentation uniquement disponible dans un PDF, ou alors consultable sur un site "statique", donc non éditable pour qui veut compléter. Cela peut être un choix de la part des dirigeants du projet, mais cela peut être aussi dû à une contrainte technique. En effet, bien souvent la création de cette documentation passe par la création d'un fichier en Docbbok, ou Odf, et exporté en PDF (pour l'impression) ou HTML (pour le site). Par expérience, je sais que, même si la source en docbook ou autre est disponible librement, les contributions sont rares, car c'est "pénible" à modifier : il faut utiliser un outil d'édition autre que le navigateur, en plus d'un autre pour télécharger les fichiers (lecture et sauvegarde). On voit ainsi tout de suite que c'est beaucoup moins aisé qu'une page wiki où il suffit juste de cliquer sur un bouton "éditer la page".

Par exemple, du temps où j'étais core-developer de Copix, nous avions la doc au format docbook[1]. Contributions externes à l'amélioration de la doc : aucune. Par contre, sur la documentation de Jelix, qui est dans un wiki, le nombre de contributions ne se compte plus, que ce soit les simples corrections d'orthographe ou l'ajout de sections entières.

Mais voilà, depuis la naissance de Jelix, j'ai souvent eu des demandes d'une version téléchargeable et imprimable de la documentation. Un nième message m'a fait passé à l'action.

J'ai donc essayé de trouver un moyen pour concilier les deux avantages :

  1. extrème facilité d'édition de manière à encourager les contributions (et donc alléger le travail des développeurs, ou au moins, une meilleure répartition du travail entre eux pour la rédaction de la doc).
  2. fournir une version téléchargeable pour pouvoir consulter hors-ligne et l'imprimer.

Impensable de remplacer le wiki (sous dokuwiki) par autre chose. Je tiens à conserver les avantages du point 1. Aussi j'ai imaginé une solution qui permet d'exporter le contenu du wiki dans un fichier Docbook. L'avantage du Docbook est qu'il existe déjà tout ce qu'il faut pour exporter le docbook vers du HTML, du PDF et autre. Bien entendu, l'export d'un ensemble de page dokuwki vers du Docbook n'existe pas, je me suis donc atteler à la tache. Voici donc maintenant comment ça fonctionne :

  • j'ai réalisé des plugins pour Dokuwiki, afin de permettre d'indiquer dans une page, des informations sur le "livre" que l'on veut créer, en particulier, le sommaire complet, c'est à dire la liste de toutes les pages ainsi que leur hierarchie et leur ordre. Ces plugins stockent ces informations en base de données[2] pour être réutilisables par d'autres composants.
  • Parmis ces autres composants : des fonctions pour le template de dokuwiki, qui affichent automatiquement des bandeaux de navigation sur chaque page du wiki qui font partie du livre. Cela a un gros avantage par rapport à "avant" : si on veut changer l'ordre d'une page, en insérer une nouvelle quelque part, on n'a plus à changer les liens qui étaient en dur dans le texte wiki des pages, et qui permettaient la navigation dans le "livre". Il y a juste à changer le sommaire. Deuxième avantage : le contenu stocké des pages ne contient que le texte du manuel. L'exporter est donc plus facile (pas de tri à faire entre le contenu à insérer dans le docbook, et les liens de navigations propre au contexte wiki).
  • On a donc maintenant en base de donnée, tout ce qu'il faut pour générer le fichier DocBook : les metas-informations sur le livre, et la liste des pages. En plus bien sûr du contenu des pages stocké par Dokuwiki dans des fichiers textes. En utilisant Jelix, j'ai réalisé un script en ligne de commande qui génére le Docbook. Il s'appuie entre autre sur WikiRenderer[3], pour lequel j'ai développé des rêgles pour parser la syntaxe wiki des pages et générer des tags docbook plutôt que HTML. Assez long à faire, sachant qu'il a fallu convertir les liens dokuwiki, importer les images utilisées dans les pages etc... Au passage, j'ai dû améliorer le moteur de WikiRenderer, la version 3.1 sera encore plus souple :-).
  • Enfin, écriture d'un script shell qui appelle le script d'export docbook, et ainsi que les commandes d'export Docbbok vers PDF. Ce script shell est installé dans le cron, permettant la génération des PDF toutes les nuits.

Au départ, je pensais que ça me prendrait quelques heures, mais j'y ai passé quelques un de mes jours de congés[4] :-) Cependant, le résultat est là : on dispose maintenant de la version PDF du manuel (ainsi que du tutoriel) qui est édité dans le wiki. Et sur le wiki, la navigation s'est largement améliorée. Il y a toutefois encore des petits choses à améliorer, comme la présentation dans le PDF, l'organisation des pages, mais le système est en place.

Seul bémol : je garde tout ces développements pour moi. Pour deux raisons :

  • C'est fait un peu à l'arrache. Il y a plein de trucs (chemins, urls et cie) en dur dans le code, il y a du code pas aussi propre que dans Jelix (oui j'ai un peu honte), et surtout vraiment pas mal de trucs spécifiques à l'installation du site et de la config du serveur.
  • Du coup, pour en faire quelque chose de distribuable, propre, y a encore du boulot. Et je n'ai plus de temps. Surtout que, qui dit distribution, dit un minimum de doc pour expliquer comment installer tout ça. Et pour ça, j'ai encore moins de temps :-)

Peut être qu'un autre jour, quand j'en aurais le courage...

Notes

[1] ils sont passé au wiki depuis

[2] c'est en contradiction avec la philosophie dokiwiki qui stock tout dans des fichiers textes, mais c'etait plus simple pour moi pour la manipulation des données

[3] c'est trop le bazar pour utiliser le parser de Dokuwiki

[4] Congé de paternité, congé restant à prendre, tout ça...