Doc as code, un parcours initiatique pour publier !

Écrire des fichiers en doc as code pour produire des notes ou des compte-rendus est relativement simple.
Construire une documentation collaborative, partagée et versionnée, c'est une autre histoire.
Et au-delà des considérations techniques, vos process de publication peuvent apporter une complexité supplémentaire...

Vous avez probablement fait vos premiers pas en doc as code. Non ?
Repartez des bases avec ce petit guide illustré pour mieux se lancer, un article pour vous montrer comment produire un document manuellement.

Ce n'est clairement pas suffisant dans un contexte de travail en équipe, et je vous propose de regarder cela d'un peu plus près.
Après avoir parlé processus et fait un tour du côté d'Asciidoctor¹, je vous emmène à la découverte d'Antora², l'outil qui m'a changé la vie !

Cette version de l'article a été publiée avec la chaîne de publication de l'écosystème Asciidoc³.

Écrire en équipe, une collaboration saine et sereine.

Vous avez appréhendé la production de fichier texte dans vos premiers documents, à l'image des fichiers source de vos applications.
Au-delà de se concentrer sur le contenu, vous allez pouvoir reprendre les pratiques de développement en vigueur sur votre projet.

Ainsi, en déversant vos documents dans un dépôt Git⁴ vous pourrez profiter des fonctionnalités d'historisation et de relecture d'un tel outil.
Se présente alors devant vous l'ère de la rédaction collaborative !

Vous pouvez observer ci-dessus l'historique de la production des documents, d'abord dans un contexte solitaire, puis dans l'ajout collaboratif de deux documents A et B.

B étant prêt en premier, il intègre la documentation avant A, dont la revue prend plus de temps.

Si la représentation des contributions ici est simple, il met en avant la possibilité de définir un processus de revue et de publication à base de l'outillage standard de développement.

Je vous invite à prendre soin de cette phase de définition du processus.

À priori simple, elle renferme des questions de gouvernance qui sont souvent primordiales à la bonne contribution de chacun.

Maintenant que vous avez le concept, passons aux techniques de publication !

Classer et hiérarchiser : comment générer toute une arborescence.

Les documents se multipliant, vous avez sans aucun doute commencé à les découper, les classer et pourquoi pas les hiérarchiser.
À ce stade, vous n'imaginez plus les générer un par un à la main !
Et c'est une bonne chose...

Asciidoctor¹ est le seul outil de génération dans l'écosystème Asciidoc.
En tout cas, il est la base sur laquelle se reposent tous les outils que nous avons déjà vus et que nous verrons plus loin.
Il est, par exemple, derrière le plugin chrome présenté dans l'article précédent
Il permet de prendre une source et de la convertir dans un ou plusieurs formats de sortie.

Précédemment, je vous ai parlé de partager vos sources à l'aide de Git⁴.
Dans la continuité, voici comment avec Asciidoctor¹ et Gitlab³, plus précisément de ses deux fonctions CI⁵ et pages⁶, vous allez pouvoir en quelques lignes produire une documentation.

Je vous propose de commencer par écrire un petit script pour générer vos documents.
Pour cela, prenez un projet avec la structure suivante.

Pour générer les fichiers, vous pouvez passer une commande proche de celle-ci :

asciidoctor \
    -R doc-as-code \            #<1>
    -D public \                 #<2>
    'doc-as-code/**/*.adoc'     #<3>

1. Répertoire racine des sources asciidoc. Permet de conserver l'arborescence dans le répertoire cible.
2. Répertoire de sortie des fichiers générés
3. Expression régulière pour trouver les fichiers à générer

Je vous invite à regarder les différentes options présentes dans la documentation de la CLI d'Asciidoctor¹ afin de générer un résultat correspondent à vos attentes.

Une fois la commande prête, je vous propose de l'utiliser avec Gitlab-CI⁵.

pages:
  stage: deploy
  image: asciidoctor/docker-asciidoctor                            #<1>
  script:
    - asciidoctor -R doc-as-code -D public 'doc-as-code/**/*.adoc' #<2>
  artifacts:
    paths:
    - public                                                       #<3>
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH                  #<4>

1. Se base sur l'image Docker de Asciidoctor
2. La commande qui génère les fichiers statiques
3. Permet de demander à Gitlab de conserver les fichiers générés et de les exposer avec sa fonction pages
4. Ne s'exécute que sur la branche principale (main par défaut)

Il vous reste à configurer votre projet pour activer Gitlab Pages, et vos documents seront partagés !
Pour cela je vous invite à consulter la documentation de Gitlab.

Passez à la vitesse supérieure : agréger et versionner plusieurs dépôts.

À ce stade, votre équipe est en capacité de produire une documentation à partir d'un dépôt de source et de la mettre à disposition de ses lecteurs.
Mais votre produit a plusieurs composants, répartis dans différents dépôts Git⁴.

Et le nombre de solutions pour agréger vos contenus n'a de limite que votre imagination...
Pour que votre créativité reste à sa place, je vais vous parler ici d'un produit en particulier : Antora².

Cet outil, intégrant directement l'écosystème Asciidoc⁷ va vous permettre de produire un site statique en assemblant les documentations de vos différents composants (alias dépôt Git⁴).

Il vous faudra un dépôt qui contiendra un playbook définissant le contenu du site à générer et une structure particulière dans vos dépôts.

Le playbook peut être contenu dans votre composant principal. Dans ce cas la séparation des responsabilités n'est pas pleinement respecté, mais peut simplifier votre agrégation

Voici le playbook:

site:
  title: Vos projets
  start_page: votre-projet::index.adoc
content:
  sources:
  - url: https://votre-gitlab.com/votre/groupe/votre-projet.git   #<1>
    branches: develop                                             #<2>
    start_path: docs                                              #<3>
  - url: https://votre-gitlab.com/votre/groupe/votre-super-projet.git
    branches: [2.0, 1.0]                                          #<4>

1. URL du dépôt git du composant.
2. Noms des branches où trouver la doc à générer
3. Chemin relatif de l'emplacement du fichier antora.yml
4. Plusieurs branches => plusieurs versions de la documentation.

Vous avez ici la possibilité d'indiquer à Antora de générer plusieurs versions de votre documentation pour un même composant.

Cette fonctionnalité se repose sur des tags ou des branches positionnées dans vos dépôts.

Coté projet, vous devrez écrire un fichier de configuration et à réorganiser vos fichiers⁸.

Antora ajoute une notion de module particulièrement pratique pour regrouper vos documents par catégorie.

Cependant, je vous déconseille de l'utiliser au départ.
Laisser vous le temps de vous familiariser avec l'organisation des sources dans Antora.

name: votre-projet            #<1>
version: current              #<2>
title: Votre projet           #<3>
nav:
- modules/ROOT/nav-begin.adoc #<4>
- modules/ROOT/nav-end.adoc

1. Clé du projet utilisée pour les liens
2. Nom de la version qui sera générée (doit changer pour chaque branche générée.)
3. Nom du projet
4. Lien vers les fichiers de navigation utilisés pour la construction du menu

Les fichiers de navigation doivent être écrits manuellement.

Alors, prêts à produire votre documentation ?

Avec Asciidoctor¹ et Antora², vous l'avez compris, nous n'avons fait que survoler deux outils d'un écosystème dense.

La configuration et la mise en place de ces outils vous demanderont un peu d'effort et surtout la lecture de la documentation de chacun de ces outils.
Il faut d'ailleurs noter la bonne qualité de ces documentations, ce qui est rassurant pour des outils censés vous aider à produire la vôtre !

Quoi qu'il en soit, et pour faire une nouvelle fois un rappel à l'article précédent : Keep It Simple Stupid⁹ !
Cet adage reste essentiel, autant dans les processus mis en place, que dans les outils mis en œuvre.

Cependant, la sobriété des rendus générés peut donner à vos documents un aspect côté impersonnel.
Pour palier cela, moyennant un peu de code, vous pouvez personnaliser les designs de sortie, mais ceci est une autre histoire...

1. https://docs.asciidoctor.org/ ↩

2. https://docs.antora.org/antora/latest/Antora ↩

3. https://asciidoc.org/ ↩

4. https://git-scm.com/ ↩

5. https://about.gitlab.com/ ↩

6. https://docs.gitlab.com/ee/ci/ ↩

7. https://fr.wikipedia.org/wiki/Principe_KISS ↩

8. https://fr.wikipedia.org/wiki/Principe_KISS/user/project/pages/ ↩

9. https://docs.gitlab.com/ee/user/project/pages/ ↩