Antora

1. Présentation

Antora est un générateur de sites web qui lit des pages sources au format Asciidoc pour générer des pages HTML. Il existe différentes versions disponibles, développées en Java, Ruby et JavaScript.

Pour réaliser la génération de pages HTML, Antora s’appuie sur Asciidoctor, un processeur de texte rapide, open source et basé sur Ruby qui lit des documents AsciiDoc pour les convertir en un modèle de document et ensuite, générer des documents en différents formats : HTML 5, DocBook 5, PDF, EPUB 3, etc.

AsciiDoc est un langage de balisage léger, adapté à la rédaction de livres et d’articles, proposant une richesse sémantique similaire à DocBook. Un document écrit en AsciiDoc forme déjà un document lisible par des humains tout en étant interprétable par des programmes.

Dans ce tutoriel, vous allez tout d’abord installer et exécuter Antora sur un projet existant et ensuite, créer et configurer un projet de développement contenant une documentation technique.$ Ce projet sera utilisé dans les prochaines séances de TP.

Ce tutoriel doit être réalisé individuellement ou en binôme.

2. Installation

Antora s’installe avec NPM, à l’intérieur d’un dossier, comme tout autre paquet JavaScript :

mkdir docs-site && cd docs-site
node -e "fs.writeFileSync('package.json', '{}')"
npm i -D -E antora

Pour vérifier que Antora a bien été installé, exécutez la commande suivante :

npx antora -v

Si tout s’est bien passé, vous aurez comme réponse une liste des paquets installés:

$ npx antora -v
@antora/cli: 3.1.9
@antora/site-generator: 3.1.9

3. Un exemple simple

Pour produire un site de documentation, Antora a besoin d’un playbook.

Dans le dossier doc-site, créez un nouveau fichier nommé antora-playbook.yml et remplissez-le avec les informations de configuration listées ci-dessous. Ce fichier playbook nous permettra de créer un site en utilisant les dépôts de démonstration de Antora.

Listing 1. antora-playbook.yml
site:
  title: Antora Docs
  start_page: component-b::index.adoc #(1)
content:
  sources: #(2)
  - url: https://gitlab.com/antora/demo/demo-component-a.git
    branches: HEAD
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui: #(3)
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
1 Une page d’un de composant qui sera utilisée comme page d’accueil de votre site.
2 La catégorie sources contient la liste des emplacements des dépôts git, des modèles de noms de branches et d’autres propriétés de dépôts que Antora utilise lors de l’agrégation du contenu du site.
3 La catégorie ui contient des clés qui spécifient l’emplacement du bundle d’interface utilisateur et la façon dont il doit être traité.

4. Exécuter Antora

Dans le terminal, assurez-vous d’être dans le répertoire doc-site, puis tapez :

npx antora --fetch antora-playbook.yml

Naviguez jusqu’au répertoire docs-site/build/site et ouvrez le fichier index.html dans votre navigateur pour voir le résultat. Félicitations, vous avez réussi à créer votre premier site avec Antora.

5. Le format Asciidoc

AsciiDoc est le le format des contenus de Antora. AsciiDoc est idéal pour écrire de la documentation car il est lisible, concis, extensible et facile à apprendre.

Un peu de lecture:

6. Travail à faire

Création d’un projet

  1. Créez un projet nommé "QuizMaker" sur le serveur GitLab de Nantes Université.

  2. Toujours dans GitLab, ajoutez "#DESIGN-2025" à la description du projet. Cela permettra aux enseignants d’identifier les projets de ce module.

  3. Invitez l’utilisateur sunye-g-clone à être membre du projet, avec le rôle Reporter.

  4. Invitez aussi votre collègue, si vous travaillez en binôme

  5. Clonez le projet sur votre compte, pour commencer à travailler

Ajout d’un module de documentation

  1. Dans la copie locale, créez un répertoire nommé quizmaker-doc, qui contiendra la documentation de votre projet

  2. À l’intérieur de ce répertoire, suivez l’organisation de contenu proposée par Antora, pour organiser la documentation de votre projet.

  3. Toujours à l’intérieur de ce répertoire, créez un fichier nommé antora.yml et ajoutez-y les lignes suivantes:

    name: conception
title: Conception du projet QuizMaker
version: 1.0.0
asciidoc:
  attributes:
    source-language: asciidoc@
    xrefstyle: short@
    listing-caption: Listing@
    example-caption: true
    experimental: true
nav:
- modules/ROOT/nav.adoc

  4. Ajoutez à votre projet une page nommée conception.adoc, contenant une introduction à votre documentation, ainsi qu’un diagramme PlantUML simple, un diagramme de classes UML contenant 2 classes et une association.

Génération du site de documentation

  1. Installez Antora à l’intérieur de votre projet

    node -e "fs.writeFileSync('package.json', '{}')"
npm i -D -E antora asciidoctor-plantuml

  2. Créez un fichier nommé .gitignore et ajoutez-y les fichiers que vous ne souhaitez pas ajouter à Git.

    Listing 2. Exemple de fichier .gitignore pour un projet Antora
    .cache/
.idea/
build/
node_modules/
packages/*/node_modules/
reports*/
.nvmrc
npm/release.sh

  3. À la racine de la copie locale, ajoutez le fichier antora-playbook.yml et configurez votre projet.

  4. Enfin, générez la première version de la documentation

  5. Si tout marche bien, validez et publiez vos modifications

7. Pour aller plus loin

Regardez cette présentation sur Antora fait par Dan Allen (Antora project co-lead):