Aller au contenu
DevSecOps Logo DevSecOps
Docs
Blog
Blog

Antora

Mise à jour :

logo antora

Dans le domaine du développement logiciel, la documentation est essentielle pour assurer une bonne communication et une compréhension claire des projets. Antora est une solution open-source qui se distingue par sa capacité à générer des sites de documentation statiques à partir de sources Git. Il permet de structurer et de versionner efficacement la documentation, tout en offrant une flexibilité et une modularité qui répondent aux besoins des projets de toutes tailles.

Avec Antora, vous pouvez centraliser la documentation de plusieurs projets en un seul site cohérent, facilitant ainsi l’accès et la mise à jour des informations. Ce guide complet vous accompagnera à travers les différentes étapes de l’utilisation d’Antora, depuis son installation jusqu’à la personnalisation et le déploiement de votre site de documentation. Que vous soyez un débutant ou un utilisateur expérimenté, vous trouverez ici toutes les informations nécessaires pour tirer le meilleur parti de cette puissante plateforme.

Historique

Le projet a débuté en 2017, lorsqu’un groupe de développeurs a commencé à explorer les possibilités offertes par AsciiDoc, un langage de balisage léger et puissant. Ils ont rapidement réalisé qu’AsciiDoc, associé à un générateur de sites statiques, pouvait fournir une base solide pour un nouveau type de système de documentation. Ce groupe a alors décidé de créer un outil qui pourrait intégrer facilement des contenus provenant de multiples référentiels Git, en utilisant les meilleures pratiques de développement et de gestion de versions.

Depuis sa première version publique, Antora a connu une adoption croissante. Les premières versions se sont concentrées sur la création d’une infrastructure robuste pour la génération de sites de documentation à partir de sources Git. Rapidement, la communauté a contribué à l’amélioration de l’outil, ajoutant des fonctionnalités telles que la gestion avancée des versions, le support de thèmes personnalisables et une meilleure intégration avec d’autres outils de développement.

L’impact d’Antora a été significatif, en particulier dans les projets open-source où une documentation claire et à jour est essentielle. Antora a permis à de nombreux projets de centraliser et de standardiser leur documentation, rendant ainsi les informations plus accessibles et compréhensibles pour les utilisateurs et les développeurs.

La communauté autour d’Antora s’est également développée, avec de nombreux contributeurs et utilisateurs partageant leurs expériences, leurs améliorations et leurs extensions. Des conférences et des ateliers sur Antora ont été organisés, renforçant encore la diffusion de bonnes pratiques en matière de documentation.

L’avenir d’Antora semble prometteur, avec de nombreuses améliorations prévues et une adoption continue dans diverses industries. Les développeurs d’Antora travaillent constamment à l’ajout de nouvelles fonctionnalités et à l’amélioration de l’expérience utilisateur, tout en gardant l’outil simple et intuitif.

Fonctionnalités principales

Antora est riche en fonctionnalités qui facilitent la gestion, la structuration et la publication de la documentation. Ces fonctionnalités sont conçues pour répondre aux besoins des projets de documentation complexes et pour améliorer l’efficacité et la cohérence des documents produits. Dans ce chapitre, je vais explorer en détail les principales fonctionnalités d’Antora.

Génération de sites statiques

L’une des caractéristiques fondamentales d’Antora est sa capacité à générer des sites de documentation statiques. Ces sites sont construits à partir de sources Git, permettant ainsi une gestion de version fluide et une collaboration facile entre les contributeurs. Une fois généré, le site peut être déployé sur n’importe quel serveur web sans nécessiter de backend dynamique, ce qui améliore les performances et la sécurité.

Terminal window
antora antora-playbook.yml

Gestion de versions

Antora excelle dans la gestion des versions de documentation. Chaque composant de documentation peut être versionné indépendamment, ce qui permet de maintenir des versions spécifiques de la documentation alignées avec les versions du logiciel. Cette fonctionnalité est particulièrement utile pour les projets en évolution rapide, où les fonctionnalités et les interfaces peuvent changer fréquemment.

content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [v1.0, v2.0, master]

Modularité

La modularité est un autre point fort d’Antora. La documentation est organisée en composants et modules, ce qui permet de structurer le contenu de manière logique et de le réutiliser facilement. Un composant est une collection de documents qui partagent un thème ou une fonction commune, tandis qu’un module est une subdivision d’un composant, regroupant des documents plus spécifiques.

Support d’AsciiDoc

Antora utilise AsciiDoc comme format principal pour les documents, offrant ainsi une syntaxe riche et puissante pour la rédaction de la documentation. AsciiDoc permet d’inclure des tableaux, des listes, des images, des blocs de code et bien plus encore, tout en restant lisible dans sa forme brute.

= Titre du Document
:author: Auteur
:revdate: 2024-06-17


== Introduction


Ceci est une introduction à notre documentation avec **Antora**.

Playbook de configuration

Le playbook d’Antora est un fichier de configuration central qui définit les sources de documentation, les paramètres de génération de site et d’autres configurations nécessaires. Il permet de centraliser toutes les configurations requises pour générer et déployer le site de documentation.

site:
  title: Documentation du Projet
  start_page: composant::module@version:index.adoc


content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [master]


output:
  dir: ./build/site

Thématisation

Antora permet de personnaliser l’apparence du site de documentation à l’aide de thèmes. Vous pouvez utiliser les thèmes fournis par défaut ou créer vos propres thèmes pour répondre aux besoins spécifiques de votre projet. La personnalisation peut inclure des styles CSS, des templates HTML et d’autres éléments visuels.

ui:
  bundle:
    url: https://gitlab.com/votre-repo/antora-ui-bundle.git
    branches: [master]

Recherche intégrée

Les sites générés par Antora incluent une fonctionnalité de recherche intégrée qui permet aux utilisateurs de trouver rapidement les informations dont ils ont besoin. Cette fonctionnalité est essentielle pour les grandes bases de documentation où la navigation manuelle peut être fastidieuse.

Gestion des dépendances

Antora peut gérer les dépendances entre différents composants de documentation, permettant ainsi de créer des liens et des références croisées entre des documents situés dans des composants ou des modules différents. Cela facilite la création d’une documentation cohérente et interconnectée.

Intégration avec CI/CD

Antora s’intègre bien avec les pipelines CI/CD (Intégration Continue / Déploiement Continu), permettant une automatisation complète du processus de génération et de déploiement de la documentation. Cela garantit que la documentation est toujours à jour et disponible en ligne rapidement après chaque changement.

Extensibilité

Grâce à sa nature open-source, Antora est hautement extensible. Les utilisateurs peuvent développer et partager des plugins pour ajouter de nouvelles fonctionnalités ou améliorer les fonctionnalités existantes. Cette extensibilité permet à Antora de s’adapter aux besoins spécifiques de divers projets.

Concepts de base

Pour utiliser efficacement Antora, il est essentiel de comprendre ses concepts fondamentaux. Ces concepts permettent de structurer et de gérer la documentation de manière organisée et cohérente. Dans ce chapitre, je vais détailler les principaux concepts d’Antora.

Composants

Un composant dans Antora est une unité de documentation indépendante, qui regroupe des documents ayant un thème ou une fonction commune. Chaque composant peut avoir plusieurs versions, ce qui permet de maintenir des documents spécifiques à chaque version d’un logiciel ou d’un projet.

Par exemple, si vous documentez une application web, vous pouvez avoir un composant pour l’API

, un autre pour la documentation utilisateur et un troisième pour les guides de développement.

Modules

Les modules sont des subdivisions des composants. Ils permettent d’organiser la documentation en unités logiques plus petites, comme des chapitres ou des sections. Chaque module contient un ensemble de fichiers de documentation, généralement en AsciiDoc, qui couvrent des sujets spécifiques.

Par exemple, dans un composant API, vous pouvez avoir des modules pour l’authentification, les points de terminaison de l’utilisateur et les erreurs courantes.

Pages

Les pages sont les documents individuels qui constituent les modules. Chaque page est un fichier AsciiDoc qui traite d’un sujet particulier. Les pages sont la plus petite unité de contenu dans Antora.

= Titre du Document
:author: Auteur
:revdate: 2024-06-17


== Introduction


Ceci est une introduction à notre documentation avec Antora.

La navigation dans Antora est définie à l’aide de fichiers de navigation qui permettent de structurer la façon dont les utilisateurs parcourent la documentation. Ces fichiers spécifient les titres des sections et les liens vers les pages correspondantes.

nav:
  - title: Guide d'Utilisation
    items:
      - title: Introduction
        url: modules/ROOT/pages/introduction.adoc
      - title: Installation
        url: modules/ROOT/pages/installation.adoc

Playbook

Le playbook est un fichier de configuration central qui définit les sources de documentation, les paramètres de génération de site et d’autres configurations nécessaires. C’est le point de départ pour générer le site de documentation avec Antora.

site:
  title: Documentation du Projet
  start_page: composant::module@version:index.adoc


content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [master]


output:
  dir: ./build/site

Pages d’Index

Les pages d’index servent de points d’entrée pour les composants et les modules. Elles fournissent un aperçu du contenu et permettent de naviguer facilement entre les sections.

= Documentation du Projet
:page-nav_order: 1


== Introduction


Bienvenue dans la documentation du Projet. Utilisez le menu pour naviguer à travers les différentes sections.

Variables et Attributs

Les variables et attributs dans Antora permettent de personnaliser et de réutiliser des morceaux de texte ou des configurations dans plusieurs documents. Ils sont définis dans les fichiers AsciiDoc et peuvent être utilisés pour insérer des informations dynamiques comme des versions de logiciel ou des chemins de fichiers.

:project-name: MonProjet
:version: 1.0


= Documentation de {project-name} v{version}

Images et Ressources

Antora permet d’inclure facilement des images et d’autres ressources dans la documentation. Les ressources peuvent être stockées dans des répertoires spécifiques et référencées dans les fichiers AsciiDoc.

image::images/logo.png[Mon Logo]

Liens et Références

Les liens et références permettent de créer des connexions entre différentes parties de la documentation. Ils peuvent pointer vers des pages internes, des sections spécifiques ou des ressources externes.

Voir la documentation complète sur la page suivante: <<installation, Installation>>.

Gestion des Dépendances

Antora gère les dépendances entre différents composants et modules de documentation. Cela permet de créer des références croisées et de s’assurer que toutes les parties de la documentation sont cohérentes et à jour.

En comprenant ces concepts de base, vous serez en mesure de structurer et de gérer votre documentation avec Antora de manière efficace et organisée. Ces concepts forment la base sur laquelle repose toute la puissance et la flexibilité d’Antora.

Installation et configuration

Pour commencer à utiliser Antora, il est essentiel de suivre quelques étapes d’installation et de configuration. Dans ce chapitre, je vais vous guider à travers le processus d’installation d’Antora et la configuration initiale de votre projet de documentation.

Prérequis

Avant d’installer Antora, assurez-vous que vous avez les prérequis suivants :

  • Node.js (version 12 ou supérieure)
  • npm (Node Package Manager)

Vous pouvez vérifier les versions installées de Node.js et npm en utilisant les commandes suivantes :

Terminal window
node -v
npm -v

Installation d’Antora

Antora est distribué via npm. Pour installer Antora globalement sur votre système, utilisez la commande suivante :

Terminal window
npm install -g @antora/cli @antora/site-generator-default

Cette commande installe à la fois le CLI (Command Line Interface) d’Antora et le générateur de site par défaut.

Création de votre premier projet

Après avoir installé Antora, vous pouvez créer la structure de base de votre projet de documentation. Commencez par créer un répertoire pour votre projet :

Terminal window
mkdir mon-projet-doc
cd mon-projet-doc

Configuration du playbook

Le playbook est un fichier de configuration YAML qui définit les sources de documentation, les paramètres de génération du site et d’autres configurations nécessaires. Créez un fichier nommé antora-playbook.yml dans votre répertoire de projet et ajoutez-y le contenu suivant :

site:
  title: Documentation de MonProjet
  start_page: composant::module@version:index.adoc


content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [master]


output:
  dir: ./build/site

Ce playbook spécifie les éléments suivants :

  • title : Le titre de votre site de documentation.
  • start_page : La page de démarrage de votre documentation.
  • sources : Les sources de contenu, ici un dépôt Git.
  • output : Le répertoire où le site généré sera stocké.

Structure des répertoires

La structure de votre projet doit suivre certaines conventions pour qu’Antora puisse l’interpréter correctement. Voici un exemple de structure de répertoires :

mon-projet-doc/
├── antora-playbook.yml
├── composant/
│   ├── modules/
│   │   ├── ROOT/
│   │   │   ├── pages/
│   │   │   │   └── index.adoc
│   │   │   └── nav.adoc
  • modules/ROOT/pages/ : Contient les fichiers de documentation en AsciiDoc.
  • nav.adoc : Fichier de navigation pour définir la structure du site.

Rédaction de la documentation

Commencez à rédiger votre documentation en créant des fichiers AsciiDoc. Par exemple, créez un fichier index.adoc dans le répertoire pages :

= Documentation de MonProjet
:author: Votre Nom
:revdate: 2024-06-17


== Introduction


Bienvenue dans la documentation de MonProjet. Ce document vous guidera à travers les fonctionnalités et l'utilisation de notre projet.

Génération du site

Pour générer le site de documentation, utilisez la commande suivante dans le répertoire de votre projet :

Terminal window
antora antora-playbook.yml

Cette commande lira le playbook, récupérera les sources de contenu et générera le site dans le répertoire spécifié (./build/site).

Vérification et débogage

Après la génération, vous pouvez ouvrir le fichier index.html dans votre navigateur pour vérifier que le site est correctement généré. Si vous rencontrez des erreurs, vérifiez les messages de la console pour identifier et résoudre les problèmes.

Automatisation avec npm scripts

Pour simplifier l’exécution des commandes, vous pouvez ajouter des scripts npm dans votre fichier package.json :

{
  "name": "mon-projet-doc",
  "version": "1.0.0",
  "scripts": {
    "build": "antora antora-playbook.yml",
    "serve": "http-server ./build/site"
  },
  "devDependencies": {
    "@antora/cli": "^2.3.0",
    "@antora/site-generator-default": "^2.3.0",
    "http-server": "^0.12.3"
  }
}

Ensuite, vous pouvez utiliser les commandes suivantes pour générer et servir votre site localement :

Terminal window
npm run build
npm run serve

En suivant ces étapes, vous serez en mesure d’installer Antora, de configurer votre projet de documentation et de générer votre premier site de documentation. Les chapitres suivants aborderont la création de contenu, la gestion des versions, la personnalisation de l’apparence et le déploiement du site.

Création de documentation

Une fois Antora installé et configuré, vous pouvez commencer à créer votre documentation. Ce chapitre vous guide à travers le processus de structuration et de rédaction de la documentation en utilisant les concepts de base d’Antora.

Structuration des composants et modules

La première étape consiste à structurer votre documentation en composants et modules. Chaque composant représente une unité logique de votre projet, et chaque module est une subdivision du composant. Par exemple, si vous documentez une application web, vous pouvez avoir les composants suivants :

  • API : Documentation de l’API
  • Utilisateur : Guides et manuels pour les utilisateurs finaux
  • Développeur : Guides pour les développeurs

Chaque composant peut contenir plusieurs modules. Pour structurer votre projet, créez les répertoires appropriés dans votre dépôt de documentation.

mon-projet-doc/
├── composant-api/
│   ├── modules/
│   │   ├── ROOT/
│   │   │   ├── pages/
│   │   │   │   └── index.adoc
│   │   │   └── nav.adoc
├── composant-utilisateur/
│   ├── modules/
│   │   ├── ROOT/
│   │   │   ├── pages/
│   │   │   │   └── index.adoc
│   │   │   └── nav.adoc
├── composant-developpeur/
│   ├── modules/
│   │   ├── ROOT/
│   │   │   ├── pages/
│   │   │   │   └── index.adoc
│   │   │   └── nav.adoc

Rédaction des pages en AsciiDoc

AsciiDoc est le format utilisé par Antora pour les fichiers de documentation. Commencez à rédiger vos documents en créant des fichiers .adoc dans les répertoires pages de chaque module. Voici un exemple de fichier index.adoc pour le composant API :

= Documentation de l'API
:author: Votre Nom
:revdate: 2024-06-17


== Introduction


Cette section couvre la documentation de l'API de MonProjet. Vous y trouverez des informations sur les endpoints, les formats de requêtes et de réponses, ainsi que des exemples d'utilisation.


== Endpoints


=== Endpoint 1


Description de l'endpoint 1.


[source,json]
----
{
  "request": {
    "method": "GET",
    "url": "/api/endpoint1"
  },
  "response": {
    "status": 200,
    "body": {
      "message": "Réponse de l'endpoint 1"
    }
  }
}
----


=== Endpoint 2


Description de l'endpoint 2.


[source,json]
----
{
  "request": {
    "method": "POST",
    "url": "/api/endpoint2"
  },
  "response": {
    "status": 201,
    "body": {
      "id": "12345",
      "message": "Endpoint 2 créé"
    }
  }
}
----

Création du fichier de navigation

Pour chaque module, créez un fichier nav.adoc qui définira la structure de navigation de votre documentation. Voici un exemple pour le module API :

* Docs
** xref:index.adoc[Introduction]
** xref:endpoints.adoc[Endpoints]
** xref:auth.adoc[Authentification]

Inclusion d’images et de ressources

Antora permet d’inclure facilement des images et d’autres ressources dans votre documentation. Placez vos images dans un répertoire approprié et référencez-les dans vos fichiers AsciiDoc :

mon-projet-doc/
├── composant-api/
│   ├── modules/
│   │   ├── ROOT/
│   │   │   ├── pages/
│   │   │   │   ├── index.adoc
│   │   │   │   └── endpoints.adoc
│   │   │   ├── images/
│   │   │   │   └── diagram.png

Dans votre fichier AsciiDoc, utilisez la syntaxe suivante pour inclure une image :

image::images/diagram.png[Diagramme de l'API]

Utilisation des variables et attributs

Les variables et attributs permettent de personnaliser et de réutiliser des morceaux de texte ou des configurations dans plusieurs documents. Définissez-les dans vos fichiers AsciiDoc :

:project-name: MonProjet
:version: 1.0


= Documentation de {project-name} v{version}
:author: Votre Nom
:revdate: 2024-06-17


== Introduction


Bienvenue dans la documentation de {project-name}.

Références croisées

Créez des références croisées pour lier différentes sections ou pages de votre documentation. Cela facilite la navigation et permet aux utilisateurs de trouver rapidement les informations connexes.

Voir la documentation complète sur la page suivante: <<endpoints.adoc, Endpoints>>.

Validation et vérification

Après avoir rédigé vos documents, il est important de les valider pour s’assurer qu’ils sont correctement formatés et que toutes les références et inclusions fonctionnent comme prévu. Utilisez la commande de génération du site pour vérifier votre travail :

Terminal window
antora antora-playbook.yml

Ouvrez le site généré dans un navigateur pour vérifier que toutes les pages, images et liens fonctionnent correctement.

En suivant ces étapes, vous pouvez structurer et rédiger efficacement votre documentation avec Antora. Le prochain chapitre abordera la gestion des versions de la documentation, une fonctionnalité clé pour maintenir des documents précis et à jour tout au long du cycle de vie de votre projet.

Gestion des versions

La gestion des versions est une fonctionnalité essentielle d’Antora, permettant de maintenir des documents précis et à jour pour différentes versions de votre projet. Dans ce chapitre, je vais vous montrer comment configurer et gérer les versions de votre documentation avec Antora.

Concept de versionnement

Antora permet de versionner la documentation en utilisant les branches de votre dépôt Git. Chaque branche peut représenter une version spécifique de votre projet et Antora générera la documentation en conséquence. Cela permet aux utilisateurs d’accéder facilement aux informations pertinentes pour la version spécifique de votre logiciel qu’ils utilisent.

Configuration du playbook pour le versionnement

Pour commencer, vous devez configurer votre playbook pour inclure les branches correspondant aux différentes versions de votre documentation. Modifiez le fichier antora-playbook.yml pour spécifier les branches de votre dépôt Git :

site:
  title: Documentation de MonProjet
  start_page: composant::module@version:index.adoc


content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [v1.0, v2.0, master]


output:
  dir: ./build/site

Structuration des versions dans le dépôt Git

Assurez-vous que votre dépôt Git est structuré de manière à refléter les différentes versions de votre projet. Créez des branches pour chaque version majeure ou mineure de votre logiciel :

Terminal window
git checkout -b v1.0
git push origin v1.0


git checkout -b v2.0
git push origin v2.0

Utilisation des balises de version

Pour identifier clairement les versions dans vos documents, utilisez des balises de version dans les fichiers AsciiDoc. Par exemple, vous pouvez inclure des informations sur la version dans le titre du document :

= Documentation de MonProjet v1.0
:author: Votre Nom
:revdate: 2024-06-17

Gestion des changements entre versions

Il est important de documenter les changements entre les versions de votre logiciel. Créez une page dédiée aux notes de version ou aux changements pour chaque version :

= Notes de version pour MonProjet v1.0
:author: Votre Nom
:revdate: 2024-06-17


== Changements dans la version 1.0


* Ajout de la fonctionnalité X
* Amélioration de la performance pour Y
* Correction du bug Z

Génération de la documentation versionnée

Après avoir configuré les branches et les documents pour différentes versions, générez la documentation pour toutes les versions spécifiées dans le playbook. Utilisez la commande suivante :

Terminal window
antora antora-playbook.yml

Antora génère un site de documentation qui inclut toutes les versions spécifiées, permettant aux utilisateurs de naviguer facilement entre elles.

Pour faciliter la navigation entre les différentes versions de votre documentation, configurez les options de navigation dans vos fichiers de navigation (nav.adoc). Voici un exemple de navigation pour plusieurs versions :

* xref:ROOT:index.adoc[Documentation de MonProjet]
** xref:ROOT:notes-de-version.adoc[Notes de version]
** xref:ROOT:v1.0/index.adoc[Version 1.0]
** xref:ROOT:v2.0/index.adoc[Version 2.0]

Exemple de fichier de navigation pour une version spécifique

Dans chaque branche, vous pouvez adapter le fichier nav.adoc pour refléter la structure spécifique de cette version :

* xref:index.adoc[Introduction]
* xref:installation.adoc[Installation]
* xref:utilisation.adoc[Utilisation]
* xref:changelog.adoc[Changelog]

Vérification des versions

Après avoir généré le site, vérifiez que toutes les versions sont correctement accessibles et que les liens fonctionnent comme prévu. Naviguez entre les différentes versions pour vous assurer que les utilisateurs peuvent facilement trouver les informations spécifiques à chaque version.

Mise à jour des versions

Lorsque vous publiez une nouvelle version de votre projet, créez une nouvelle branche Git et mettez à jour votre documentation en conséquence. N’oubliez pas de modifier le playbook pour inclure la nouvelle branche et de générer à nouveau le site de documentation.

Terminal window
git checkout -b v3.0
git push origin v3.0

Mettez à jour antora-playbook.yml :

content:
  sources:
    - url: https://github.com/votre-repo/documentation.git
      branches: [v1.0, v2.0, v3.0, master]

Puis régénérez le site :

Terminal window
antora antora-playbook.yml

En suivant ces étapes, vous pouvez gérer efficacement les versions de votre documentation avec Antora. Le prochain chapitre abordera la personnalisation de l’apparence de votre site de documentation à l’aide de thèmes.

Thématisation

La thématisation permet de personnaliser l’apparence de votre site de documentation pour qu’il corresponde à l’identité visuelle de votre projet ou organisation. Antora offre une flexibilité considérable pour créer et appliquer des thèmes personnalisés. Dans ce chapitre, je vais vous montrer comment utiliser et créer des thèmes dans Antora.

Utilisation des thèmes par défaut

Antora est livré avec un thème par défaut, mais vous pouvez utiliser d’autres thèmes disponibles ou créer le vôtre. Pour utiliser un thème existant, vous devez spécifier son URL dans le playbook. Voici un exemple de configuration pour utiliser un thème personnalisé :

ui:
  bundle:
    url: https://gitlab.com/votre-repo/antora-ui-bundle.git
    branches: [master]

Structure d’un thème Antora

Un thème Antora est un package qui contient les fichiers de style, les templates et les ressources nécessaires pour personnaliser l’apparence du site. Voici une structure de base pour un thème Antora :

antora-ui-bundle/
├── assets/
│   ├── css/
│   │   └── styles.css
│   ├── images/
│   │   └── logo.png
├── layouts/
│   ├── default.hbs
│   ├── page.hbs
├── partials/
│   ├── footer.hbs
│   ├── header.hbs
├── package.json

Création d’un thème personnalisé

Pour créer votre propre thème, commencez par cloner un thème existant ou créez un nouveau répertoire pour votre thème. Voici un exemple de fichier package.json pour un thème Antora :

{
  "name": "antora-ui-bundle",
  "version": "1.0.0",
  "description": "Un thème personnalisé pour Antora",
  "main": "index.js",
  "author": "Votre Nom",
  "license": "MIT",
  "dependencies": {
    "handlebars": "^4.7.6"
  }
}

Personnalisation des styles

Pour personnaliser les styles, modifiez les fichiers CSS dans le répertoire assets/css. Vous pouvez ajouter vos propres styles ou modifier les styles existants pour correspondre à l’identité visuelle de votre projet.

body {
  font-family: Arial, sans-serif;
  background-color: #f5f5f5;
}


header {
  background-color: #333;
  color: white;
  padding: 10px 0;
}


header img {
  max-height: 50px;
}


footer {
  background-color: #333;
  color: white;
  text-align: center;
  padding: 10px 0;
}

Modification des templates

Antora utilise Handlebars pour les templates. Les fichiers de template dans le répertoire layouts définissent la structure HTML de vos pages. Vous pouvez modifier ces fichiers pour personnaliser la disposition de votre site.

Par exemple, le fichier default.hbs peut ressembler à ceci :

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{title}}</title>
  <link rel="stylesheet" href="{{rootPath}}/assets/css/styles.css">
</head>
<body>
  <header>
    <div class="container">
      <img src="{{rootPath}}/assets/images/logo.png" alt="Logo">
      <h1>{{title}}</h1>
    </div>
  </header>
  <main>
    {{{content}}}
  </main>
  <footer>
    <div class="container">
      <p>&copy; 2024 MonProjet. Tous droits réservés.</p>
    </div>
  </footer>
</body>
</html>

Gestion des ressources

Vous pouvez ajouter des images et d’autres ressources dans le répertoire assets/images et les référencer dans vos templates ou fichiers AsciiDoc.

image::images/logo.png[Logo]

Application du thème

Après avoir créé et personnalisé votre thème, mettez-le à jour dans votre dépôt Git et configurez le playbook pour utiliser ce thème :

ui:
  bundle:
    url: https://gitlab.com/votre-repo/antora-ui-bundle.git
    branches: [master]

Test du thème

Générez votre site de documentation avec le nouveau thème pour voir les modifications appliquées :

Terminal window
antora antora-playbook.yml

Ouvrez le site généré dans un navigateur pour vérifier que le thème est correctement appliqué et que toutes les personnalisations fonctionnent comme prévu.

Exemple de thème personnalisé

Voici un exemple de thème personnalisé minimaliste pour Antora :

antora-ui-bundle/
├── assets/
│   ├── css/
│   │   └── styles.css
│   ├── images/
│   │   └── logo.png
├── layouts/
│   ├── default.hbs
├── package.json

Avec le fichier styles.css suivant :

body {
  font-family: 'Open Sans', sans-serif;
  background-color: #ffffff;
  color: #333;
}


header {
  background-color: #4CAF50;
  color: white;
  padding: 10px 0;
}


header img {
  max-height: 50px;
}


footer {
  background-color: #4CAF50;
  color: white;
  text-align: center;
  padding: 10px 0;
}

Et le fichier default.hbs :

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{title}}</title>
  <link rel="stylesheet" href="{{rootPath}}/assets/css/styles.css">
</head>
<body>
  <header>
    <div class="container">
      <img src="{{rootPath}}/assets/images/logo.png" alt="Logo">
      <h1>{{title}}</h1>
    </div>
  </header>
  <main>
    {{{content}}}
  </main>
  <footer>
    <div class="container">
      <p>&copy; 2024 MonProjet. Tous droits réservés.</p>
    </div>
  </footer>
</body>
</html>

En suivant ces étapes, vous pouvez personnaliser et thématiser votre site de documentation Antora pour qu’il corresponde à l’identité visuelle de votre projet. Le prochain chapitre abordera le déploiement de votre site de documentation.

Déploiement

Après avoir généré et personnalisé votre site de documentation avec Antora, l’étape suivante consiste à le déployer sur un serveur web afin qu’il soit accessible aux utilisateurs. Dans ce chapitre, je vais vous expliquer les différentes méthodes pour déployer votre site de documentation.

Préparation des fichiers

Avant de déployer votre site, assurez-vous que tous les fichiers nécessaires ont été générés et sont prêts à être copiés sur le serveur. Le répertoire de sortie défini dans votre playbook (./build/site par défaut) contient tous les fichiers de votre site de documentation.

Déploiement sur un serveur web

La méthode la plus simple pour déployer votre site de documentation est de copier les fichiers générés sur un serveur web. Voici quelques options populaires pour le déploiement :

Serveur Apache ou Nginx

Pour déployer votre site sur un serveur Apache ou Nginx, vous devez copier le contenu du répertoire de sortie vers le répertoire racine du serveur web.

Apache

  1. Copiez les fichiers de votre site vers le répertoire racine d’Apache, généralement /var/www/html :

    Terminal window
    sudo cp -r ./build/site/* /var/www/html/

  2. Redémarrez Apache pour appliquer les modifications :

    Terminal window
    sudo systemctl restart apache2
Nginx

  1. Copiez les fichiers de votre site vers le répertoire racine de Nginx, généralement /usr/share/nginx/html :

    Terminal window
    sudo cp -r ./build/site/* /usr/share/nginx/html/

  2. Redémarrez Nginx pour appliquer les modifications :

    Terminal window
    sudo systemctl restart nginx

Serveur GitHub Pages

GitHub Pages est une solution populaire pour héberger des sites statiques directement depuis un dépôt GitHub. Pour déployer votre site de documentation sur GitHub Pages :

  1. Initialisez un nouveau dépôt Git dans le répertoire de sortie :

    Terminal window
    cd ./build/site
    git init

  2. Ajoutez tous les fichiers et effectuez un commit :

    Terminal window
    git add .
    git commit -m "Initial commit"

  3. Ajoutez l’URL de votre dépôt GitHub comme dépôt distant :

    Terminal window
    git remote add origin https://github.com/votre-utilisateur/votre-repo.git

  4. Poussez les fichiers vers la branche gh-pages :

    Terminal window
    git push -u origin master:gh-pages

Votre site sera alors disponible à l’URL https://votre-utilisateur.github.io/votre-repo.

Serveur Netlify

Netlify est un service de déploiement et d’hébergement pour les sites statiques. Pour déployer votre site de documentation sur Netlify :

  1. Connectez-vous à Netlify et créez un nouveau site en sélectionnant votre dépôt GitHub.
  2. Configurez les paramètres de construction :
    • Build command : antora antora-playbook.yml
    • Publish directory : ./build/site
  3. Déployez le site.

Netlify déclenchera automatiquement le processus de construction et déploiera votre site.

Déploiement continu avec CI/CD

Pour automatiser le déploiement de votre site de documentation à chaque modification, vous pouvez utiliser des pipelines CI/CD (Intégration Continue / Déploiement Continu). Voici un exemple de configuration pour GitHub Actions :

  1. Créez un fichier .github/workflows/deploy.yml dans votre dépôt :

    name: Deploy Documentation
    

    on:
      push:
        branches:
          - main
    

    jobs:
      build:
        runs-on: ubuntu-latest
    

        steps:
          - name: Checkout repository
            uses: actions/checkout@v2
    

          - name: Set up Node.js
            uses: actions/setup-node@v2
            with:
              node-version: '14'
    

          - name: Install Antora
            run: npm install -g @antora/cli @antora/site-generator-default
    

          - name: Build documentation
            run: antora antora-playbook.yml
    

          - name: Deploy to GitHub Pages
            uses: peaceiris/actions-gh-pages@v3
            with:
              github_token: ${{ secrets.GITHUB_TOKEN }}
              publish_dir: ./build/site

  2. Commitez et poussez ce fichier dans votre dépôt GitHub. Chaque fois que vous poussez une modification sur la branche main, GitHub Actions générera et déploiera automatiquement votre site de documentation sur GitHub Pages.

Vérification du déploiement

Après avoir déployé votre site, vérifiez que tout fonctionne correctement en visitant l’URL où votre site est hébergé. Assurez-vous que toutes les pages, liens et ressources (images, fichiers CSS, etc.) s’affichent correctement.

Maintenance et mises à jour

Assurez-vous de maintenir votre site de documentation à jour en redéployant à chaque modification importante de votre projet ou de votre documentation. Automatisez autant que possible les processus de génération et de déploiement pour réduire les erreurs et garantir que les utilisateurs disposent toujours des informations les plus récentes.

En suivant ces étapes, vous pourrez déployer et maintenir efficacement votre site de documentation généré par Antora. Le prochain chapitre abordera la conclusion et un résumé des points clés abordés dans ce guide.