Créer un site de documentation avec Antora

Créer son site de documentation avec Antora

Créer un site de documentation avec Antora

Peu importe votre projet informatique, la nécessité de stocker de la documentation est toujours présente. Le choix d’utiliser un wiki est assez courant en entreprise, mais savez-vous qu’il existe des solutions parfois plus adaptées ?

Imaginons que vous êtes développeur sur un de ces programmes, la documentation des différents projets est-elle gérée par un wiki facilement accessible et éditable ?

Votre documentation est-elle polluée par les problèmes classiques ?

  • Des pages avec des sections “à documenter”
  • Des pages avec des informations erronées
  • Des pages dépréciées
  • Des pages uniquement utiles pour une équipe ou une autre
  • Des pages avec de la documentation sur une future évolution

Vous vous demandez donc comment améliorer tout ça, pour faciliter la tâche des personnes travaillant sur les différents projets.

C’est le moment de vous pencher sur le principe de la “documentation as code”. Ça pourrait être la solution à votre besoin.

Se lancer dans l’aventure de la “documentation as code”

Voir la documentation comme du code au même titre que les sources du programme est intéressant. Vous souhaitez remplacer votre wiki actuel par un projet dédié à la documentation, et vous permettre de faire des code reviews sur ces changements. Mais cela ne corrige qu’une partie du problème, vous avez seulement remplacé des pages wiki par des fichiers écrits dans un autre format comme :

Du fait de sa syntaxe simple et accessible, le format Markdown est un des plus répandus, surtout sur des sites comme GitHub ou GitLab. Malheureusement ce format est trop simple pour une documentation plus approfondie.

Le format Asciidoc est plus intéressant, il permet d’être plus expressif dans votre documentation.
L’outil associé Asciidoctor apporte des fonctionnalités utiles ainsi que des intégrations comme la génération de diagrammes avec plantuml.

Vous choisissez donc d’écrire la documentation en Asciidoctor dans chacun des projets. Cela vous permet de livrer la documentation à jour en même temps que le code associé. Même si votre programme se compose d’un ensemble de projets avec chacun sa documentation, vous souhaitez garder un site unique pour y accéder.

Les personnes derrière Asciidoctor ont récemment ouvert, à la communauté open source, un générateur de site de documentations agrégées : Antora en version stable (1.0.0).

Page d'accueil du site Antora.org

Créer un nouveau site de documentation avec Antora / Asciidoctor

Un site généré par Antora est composé de trois éléments :

  • Vos projets qui contiennent leurs documentations
  • Le playbook qui configure la génération du site de documentation
  • Une UI qui définit le visuel de votre site (celle par défaut conviendra)

Pour être utilisé par Antora, un projet se doit de respecter une structure de fichiers

./docs
├── antora.yml
└── modules
└── ROOT
      ├── _attributes.adoc
      ├── nav.adoc
      └── pages
          ├── _attributes.adoc
          └── index.adoc

Mettre en place la documentation as code sur vos projets

Vous vous appliquez donc à le mettre en place sur :

La documentation au format Asciidoctor est disponible dans le dossier docs.

Il n’est pas nécessaire d’utiliser cette arborescence pour guideline, qui est uniquement un projet de documentation.

Préparation de votre site de documentation

Vous créez donc un projet spécifique pour stocker le playbook.

Contenu du playbook Antora

Le contenu du playbook site.yml définit :

De plus, la documentation officielle n’en fait pas référence, car il s’agit d’un développement encore au stade expérimental, mais vous configurez la barre de navigation pour rajouter les liens utiles via un fichier header-content.hbs dans supplemental-ui/partials/.

D’autres fichiers templates sont disponibles pour remplacement dans Antora Default UI.

Générer et déployer votre nouveau site de documentation

Vous pouvez installer Antora via ce guide ou utiliser l’image docker via la commande :

$ docker run -v `pwd`:/antora --rm antora/antora --stacktrace site.yml

(où site.yml est le playbook)

Le playbook défini le dossier docs pour mettre à disposition votre nouveau site de documentation.

Visuel du site de documentation fait avec Antora

Par exemple, pour le rendre accessible sur GitHub, vous le déployez via les Github Pages de votre projet docssite.

Configuration Github pour exposer le site de documentation

La plateforme s’occupera automatiquement d’exposer le contenu du dossier /docs à l’adresse https://rlespinasse.github.io/docssite par exemple.

Partager ce nouveau site de documentation

Dorénavant, les personnes travaillant sur le programme pourront ajouter, créer, maintenir de la documentation relative à chacun des projets très facilement. Cela grâce à votre nouveau site de documentation permettant d’accéder à toutes ces pages.

Le site docs.antora.org utilise lui-même le projet Antora.

Merci à Aurélien Allienne, Antoine Méausoone, Tanguy Baudrin, et Tony Proum pour la relecture de l’article.

Vous aimerez aussi...