Créer une review app de votre documentation Antora sur GitLab

Publié le 28/12/2020

GitLab et Antora

Lors d’une de mes précédentes missions, j’ai mis en place antora pour un de mes clients. Si vous ne connaissez pas ce système de génération de site statique, sachez qu’il est initialement prévu pour agréger et générer un site de documentation unifié à partir de multiple dépôts git contenant une à plusieurs versions de documentation.

Suite à cette mise en place, mes collègues et moi-même nous sommes demandés comment mettre en place une prévisualisation de la documentation avant de merger. Je n’avais alors pas eu le temps avant ma fin de mission de répondre à cette question. Cet article a pour but de le faire.

Pourquoi vouloir une preview ?

Lorsque l’on fait de la doc as code, il est souvent intéressant de vérifier le rendu final. Cela devient même indispensable lorsque nos schémas sont construit à partir de diagram as code comme du plantUML.

En effet pour ces derniers hormis via une review app, je ne vois que les solutions suivantes pour valider l’exactitude d’un schéma :

  1. votre outil de revue de code / documentation sait interpréter votre diagramme

  2. vous générez une image en parallèle du diagramme plantUML

Autant les IDE supportent relativement bien les schémas mais ce n’est pas toujours le cas de votre outil en ligne de revue de code tel que GitLab, GitHub ou Gerrit. De plus pour les IDE cela nécessite de checkout le code et même si cela est rapide, ça l’est moins que la revue directement dans une MR/PR.

Pour la seconde solution le plus gros point noir reste la synchro des schémas. Est-on sûr que les images ont été générées avec la dernière version du fichier plantUML ? Pour ce point, vous pouvez toujours mettre en place des hooks de pre-commit, mais je vais vous présenter une autre solution.

Et si l’on utilisait les review applications pour valider les modification de notre documentation ?

Première étape, pouvoir générer la documentation d’un unique composant

De façon macroscopique antora fonctionne de la manière suivante :

  • Vous avez un aggrégateur unique qui liste tous les composants (dépôts git) à intégrer dans notre documentation.

  • Pour chacun de ses composants, l’aggrégateur récupère toutes les versions à générer (branches / tags).

  • Enfin pour chacune de ses versions, il génère un rendu statique en se basant sur une UI handlebars.

Si vous voulez une description plus précise et juste du processus, je vous invite à lire cette page de la documentation officielle.

En local, si l’on souhaite générer la documentation pour un seul composant, il est conseillé d’utiliser le mode auteur. On va donc partir de là pour créer le rendu de notre composant. Ensuite, nous passerons à l’automatisation de la génération et la prévisualisation grâce à notre CI.

Admettons que l’on ait le dépôt suivant :

├── docs
│   ├── antora.yml
│   └── modules
│       └── ROOT
│           ├── nav.adoc
│           └── pages
│               └── index.adoc
├── ...// autres fichiers de votre dépôt
└── README.adoc

On va ajouter un fichier spécifique antora à ce dépôt pour générer la documentation. Par défaut je l’appelle .local-antora-playbook.yml. Bien entendu vous êtes libre de le nommer comme vous le souhaitez. Sachez juste que local-antora-playbook.yml est utilisé généralement par le mode auteur. J’ai pour ma part préféré un fichier caché pour ne pas voir le fichier dans mon terminal lorsque j’utilise exa ou ls sans option.

Ce fichier servira à la fois pour le mode auteur et pour la prévisualisation des modifications de la documentation grâce à la CI.

On se retrouve alors avec l’arborescence suivante :

├── docs
│   ├── antora.yml
│   └── modules
│       └── ROOT
│           ├── nav.adoc
│           └── pages
│               └── index.adoc
├── ...// autres fichiers de votre dépôt
├── .gitignore
├── .local-antora-playbook.yml
└── README.adoc

Dans ce fameux fichier nous initialisons la création d’un composant de la façon suivante :

site:
  title: Review app
content:
  sources:
    - url: . (1)
      start_path: docs (2)
      branches: HEAD (3)
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
output:
  dir: ./public (4)
1 Chemin relatif vers le composant à construire
2 Chemin relatif de la documentation antora
3 Version à construire
4 Répertoire contenant le rendu de la documentation

En local, vous pouvez directement utiliser ce fichier de la manière suivante :

antora .local-antora-playbook.yml

Passons maintenant à la suite.

Seconde étape, la review app

Si vous ne connaissez pas les review applications de GitLab, je vous renvoie à la documentation officielle. Vous pouvez également visionner cette courte vidéo par l’ami Philippe Charrière. Elle présente les gitlab pages et les review applications que nous allons utiliser.

Premièrement nous allons créer un fichier .gitlab-ci.yaml. Si vous en avez déjà un, vous allez devoir lui ajouter 2 jobs.

Le premier servira à créer la review application et l’environnement associé dans GitLab. Le second servira à arrêter cette review application et l’environnement associé.

Voici mon fichier complet. Les explications sont juste après.

image: antora/antora

stages:
  - publish

# create review app + preview environment
pages:preview:
  stage: publish
  script:
    - echo "🎲 publishing for preview"
    - antora --title "MR-${CI_MERGE_REQUEST_IID} doc preview" --url https://${CI_PROJECT_ROOT_NAMESPACE}.gitlab.io/-/${CI_PROJECT_NAME}/-/jobs/${CI_JOB_ID}/artifacts/public/ .local-antora-playbook.yml (1) (2)
  artifacts:
    paths:
      - public (3)
  rules:
    - if: $CI_MERGE_REQUEST_IID (4)
  environment:
    name: preview/${CI_PROJECT_NAME}/${CI_COMMIT_REF_NAME}
    url: https://${CI_PROJECT_ROOT_NAMESPACE}.gitlab.io/-/${CI_PROJECT_NAME}/-/jobs/${CI_JOB_ID}/artifacts/public/single-component-review-app/index.html (5)
    on_stop: pages:preview:stop

# remove the review environment
pages:preview:stop: (6)
  stage: publish
  rules:
    - if: $CI_MERGE_REQUEST_IID
      when: manual
  allow_failure: true
  environment:
    name: preview/${CI_PROJECT_NAME}/${CI_COMMIT_REF_NAME}
    action: stop
  script:
    - echo "👋 bye"
1 On surcharge le titre de la documentation afin d’indiquer que c’est la preview de la MR-n°X
2 On doit surcharger l’url racine de la documentation pour que antora génère correctement les liens
3 On déclare où sera l’artefact à publier pour notre application
4 Ce job n’est actif que pour les merge requests
5 On déclare l’url à laquelle on retrouvera notre documentation. Les points suivants sont à prendre en compte dans le cas d’une preview de documentation antora. single-component-review-app correspond au nom du composant dans le fichier antora.yml. index.html correspond au nom de la page sur laquelle vous voulez atterir par défaut (ici: index.adoc ⇒ index.html)
6 C’est ici que vous retrouvez tout le job de suppression.

Vous pouvez également retrouver tous le code source de cet article dans ce dépôt gitlab.

Limites connues

J’ai trouvé quelques limites à la prévisualisation de merge request de documentation.

  • la génération des liens inter-composant antora échoue

  • je n’ai pas réussi à faire de review application pour les projets présents dans des sous-groupes. J’ai peut être eu un loupé dans ma recherche d’information.

Lien utiles

Si vous souhaitez mettre en place la solution antora dans votre entreprise et que vous avez besoin d’aide, je suis disponible pour du consulting sur quelques jours ou pour un accompagnement plus régulier de vos équipes.

Vous pouvez retrouver mes coordonnées professionnelles sur mon site.