Dans le but de compiler toutes les informations relatives à CLUB1, une documentation toute neuve a été créée. Son but est de devenir la source de référence des information techniques sur le serveur. En effet, auparavant, les informations étaient réparties entre plusieurs pages du site, un dépôt GitHub et des articles du journal. L'idée était donc premièrement de rassembler toutes ces informations au même endroit. Deu­xième­ment, elle devait être versionnée (avec Git bien-sûr) pour pouvoir travailler sérieusement dessus à plusieurs et pour être certains de ne jamais perdre de données, grâce au fonctionnement distribué de Git. Finale­ment, il fallait que le language de rédaction de la documentation soit le Mark­down, car il est très simple à apprendre et à lire et que c'est le plus utilisé dans le reste des projets de CLUB1.

Rassurez-vous, l'idée avec cette nouvelle doc n'est pas d'arrêter d'alimenter le journal. Nous continuerons d'ajouter des nouvelles sur le site lorsque certaines avancées auront été réalisées (comme dans le cas présent 😉). En fait la grosse différence entre la documentation et le journal, c'est que la doc a pour but d'évoluer et d'être tout le temps à jour, tandis qu'un article du journal décrit une information à un instant t et n'est pas vraiment voué à être mis à jour.

La petite histoire

Une fois que le cahier des charges de cette documentation a été défini, il restait encore à choisir la solution technique pour le mettre en œuvre.
Pour avoir passé un certain temps à lire de la doc technique en ligne, nous avions déjà en tête le logiciel Sphinx qui, allié au thème Read­The­Docs, produit des documentations plutôt agréables à lire. C'est notamment ce combo qui permet de générer la documentation du kernel Linux (assez conséquente), celle de Web­late ou encore de Cert­bot.

En plus de l'esthétique de la documentation Web produite, plusieurs aspects de Sphinx nous avaient attiré. Tout d'abord la version HTML qu'il génère est entièrement statique mais propose tout de même une barre de recherche (la recherche se fait donc entièrement côté client, à l'aide d'un index, généré en même temps que le site). Ensuite, il a la capacité de compiler la documentation dans tout un tas de formats de sortie (finalement ce n'était pas si important que ça 😅). Les admonitions—des blocs de notes ou d'avertissements—que Sphinx permet d'insérer dans le contenu ont retenu notre attention pour les tutoriels que l'on comptait inclure dans cette documentation. La possibilité de traduire le contenu à l'aide de gettext nous permettait d'envisager une version anglaise. Et finalement, la maturité du projet et son utilisation très répandue nous rassurait sur son efficacité et sa pérénité.

Site web et version physique

Finalement, de tous les formats de sortie possibles seuls deux seront réellement utilisés : Le format HTML pour la version Web et le format PDF­LaTeX pour un export PDF.
Ce dernier n'est pas anodin. En effet, le but d'avoir une version PDF n'est pas vraiment de permettre aux gens de la télécharger et la consulter avec leur lecteur de PDF favori (même si c'est très cool). Le réel intérêt de ce format réside dans son imprimabilité !
Comme les expériences des différents workshop ont pu nous l'apprendre, la transmission de connaissances liés à internet fonctionne 710% mieux lorsqu'il y a rencontre physique. Pour aller dans ce sens, comme pour le fait d'avoir sous la mains les bouquins de la bibliothèque, on pourra maintenant tendre la Doc à un·e autre membre CLUB1, tout en lui adressant un large sourir (ce qu'un site Web ne pourra jamais faire, malgré tous les smileys du monde).

Customisation à l'extrème

Bien que Sphinx ne soit prévu à l'origine que pour fonctionner avec re­Stru­ctu­red­Text, l'extension MyST recommandée par la documentation officielle, permet de lui ajouter le support de Mark­down. Et, malgré quelques écueils comme les liens vers un titre d'une page qu'il faut activer, ça fonctionne globalement bien. Mais reST proposant plus de fonctionnalités que Mark­down, MyST se voit forcé d'étendre la syntaxe de Mark­down afin d'en combler les lacunes, ce qui la complexifie un peu.

Très rapidement, le Makefile et le fichier de conf sont fortement customisés, principalement pour que le système de build permette de facilement gérer plusieurs langues, car bien que Sphinx supporte la traduction du contenu, rien n'est prévu de base pour pouvoir générer toutes les langues d'un coup, il faut le scripter soi-même. Qu'à cela ne tienne, c'est rigolo de faire le Makefile ultime 😁.

Le template LaTeX aura lui aussi été lourdement customisé afin que le rendu se rapproche plus de la version Web. Le support des emojis, par exemple, aura nécessité une certaine quantité de recherches et de temps. Un petit paquet d'extensions Sphinx aura également été codé pour ajouter certaines fonctionnalités importantes à nos yeux, en particulier des infobulles au survol pour les termes de glossaire (mots colorés en bleu et soulignés en pointillé). Et cerise sur le gâteau, l'ensemble de la documentation est automatiquement compilé et publié à chaque fois qu'une modification est mergée dans la branche princiale. Maintenant que tout ça est fait, il ne reste plus qu'à améliorer le contenu de la documentation ! 🤓

Modifiable

Bien-sûr, tout le monde peut y participer, c'est tout de même ce que l'utilisation de Git nous offre de base. GitHub quant à lui permet de faciliter ces modifications pour les non-infor­ma­ti­ciens, mais il est évidemment toujours possible de s'en passer (git send-email, dépôt accessible en lecture via HTTP, etc.). Toutes les informations à propos de comment participer à la documentation se trouvent… dans la doc elle-même, dans la section meta-do­cu­men­ta­tion !

Ce qu'on peut y trouver

Comme expliqué précedemment, le but principal est de regrouper toutes les informations techniques concernant le serveur CLUB1. Le premier chapitre est pour l'instant reservé aux informations générales. L'ensemble des services qu'il propose sont décrits et expliqués en détail dans le chapitre deux. En plus de fournir des informations sur les services, cette nouvelle documentation devait contenir des tutoriels pour en guider l'apprentissage, ils se trouvent dans le troisième chapitre. Le quatrième chapitre est prévu pour contenir tous les sujets techniques de CLUB1 qui ne concernent pas directement les membres, il s'appelle pour le moment "documentation interne". On y trouve notamment la meta-do­cu­men­ta­tion dont on parlait plus haut. Pour finir, le dernier chapitre est un glossaire global contenant des définitions concises de certains termes importants et un index généré par Sphinx offre encore un autre moyen de naviguer dans la documentation (il est surtout utile pour la version imprimée).

Nous espérons que cette nouvelle documentation sera pour vous un plaisir à naviguer, que ce soit la version Web ou la version physique, qu'elle vous apportera les informations que vous cherchiez et vous permettra même d'en découvrir.