Remplacer votre wiki par un site de documentation

Hi, the english version of this article can be read on dev.to

Peu importe votre projet informatique, il y aura toujours un besoin de stocker de la documentation.
Le choix d'utiliser un wiki est assez courant en entreprise.

Parlons de vous, 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?

Et si vous regardez le contenu de ce wiki, vous y trouverez surement :

• 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 faire pour faciliter la tâche des personnes travaillant sur les différents projets.

À ce moment là, le principe de la documentation as code vous paraît être la solution à votre besoin.

Vous vous lancez 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 review 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 :

• le format Markdown,
• le format Asciidoc.

Du fait de sa syntaxe simple et accessible, le format Markdown est un des plus répandu, surtout sur des sites comme github ou gitlab. Mais le 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 aggrégées: Antora en version stable (1.0.0).

Vous créez votre 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

Vous mettez en place la documentation as code sur vos projets

Vous vous appliquez donc à le mettre en place sur :

• Vos APIs (api A, api B, api C),
• Vos outils (build tools),
• Votre guide de development (guidelines).

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.

Vous vous préparez à générer votre site de documentation

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

site:
  title: "Romain Lespinasse // Docs"
  start_page: guidelines::index
  url: https://rlespinasse.github.io/docssite
content:
  sources:
  - url: https://github.com/rlespinasse/api-a.git
    branches: master
    tags: v*
    start_path: docs
  - url: https://github.com/rlespinasse/api-b.git
    branches: master
    tags: v*
    start_path: docs
  - url: https://github.com/rlespinasse/api-c.git
    branches: master
    tags: v*
    start_path: docs
  - url: https://github.com/rlespinasse/buildtools.git
    branches: master
    tags: v*
    start_path: docs
  - url: https://github.com/rlespinasse/guidelines.git
    branches: master
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: ui-bundle
  supplemental_files: ./supplemental-ui
output:
  dir: ./docs

Le contenu du playbook site.yml définit :

• les informations relatives au site en lui-même via site:,
• la définition du contenu via content:,
• le theme du site via ui:,
• Le dossier de génération via output:.

La documentation officielle n'en fait pas référence, car il s'agit d'un dévelopement 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.

Vous générez et déployez 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.

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

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

Vous faites profitez aux autres du 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. 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, Hubert Sablonnière, Tanguy Baudrin, et Tony Proum pour la relecture de l'article.

Cet article a été publié en premier sur lemag.sfeir.com.