AccueilActualités informatiqueDocumentation : Le générateur de sites statiques Antora 3.0 introduit une nouvelle...

Documentation : Le générateur de sites statiques Antora 3.0 introduit une nouvelle API pour les plug-ins

Antora est un générateur de site statique pour les sites web de documentation, que l’équipe de développement vient de présenter dans sa version 3.0.0 après environ trois ans de travail. Antora lit la documentation au format AsciiDoc à partir d’un ou de plusieurs dépôts Git et génère des fichiers HTML qui peuvent ensuite être livrés par n’importe quel serveur web. Les utilisateurs du site trouvent les contenus souhaités grâce à la navigation, aux renvois et à la recherche. Si une documentation structurée par version logicielle est nécessaire, Antora crée des sous-sites individuels à partir de différentes branches et balises des dépôts Git. Dans la version 3, on trouve quelques nouvelles fonctions qui devraient faciliter le travail avec l’outil.

Sommaire

La nouvelle version se base sur Asciidoctor 2, ce qui permet, en plus de petites optimisations et de corrections de bugs, de nouvelles fonctionnalités comme les zones de texte dépliables dans Antora. Celles-ci peuvent par exemple cacher des conseils ou une solution dans un premier temps dans les tutoriels.

Comme dans la version 2, Antora suit l’approche « convention over configuration », de sorte que tous les fichiers d’exemple d’un composant se trouvent dans un répertoire « examples ». Dans le passé, cela posait régulièrement le problème que les exemples de code source se trouvaient dans d’autres répertoires selon l’outil de construction, qu’Antora ne pouvait pas les y trouver et qu’ils devaient donc être placés en copie dans le répertoire « examples ». La version 3 traite désormais aussi les symbioses Git, de sorte qu’un lien vers des fichiers ou des répertoires peut être placé dans le répertoire « examples ». Les fichiers sont ainsi disponibles pour Antora et peuvent être utilisés directement par les auteurs.

Les Resource IDs, qui permettent aux auteurs de créer des liens entre les composants et les versions, n’étaient utilisés dans Antora 2 que pour les références croisées vers d’autres pages. Depuis la version 3, ils peuvent également être utilisés pour les références aux pièces jointes et aux images liées. Les références croisées vers des pages doivent désormais toujours être accompagnées de l’extension de fichier « .adoc », car les références croisées sans extension étaient déjà obsolètes (deprecated) dans la version 2.

Toutes les modifications importantes pour Antora 3 peuvent également être utilisées dans la version actuelle du plug-in AsciiDoc pour IntelliJ. Il est disponible pour les IDE JetBrains payants et gratuits comme IntelliJ IDEA dans l’édition communautaire. Il permet aux auteurs de compléter les références croisées dans leur environnement de développement au moment de l’écriture et de les faire vérifier automatiquement.

Il est désormais possible d’enregistrer des URL fixes pour la dernière version de la documentation et la dernière pré-version. Les utilisateurs peuvent ainsi plus facilement mettre des signets et les liens pointent toujours vers la dernière version. En outre, il est possible de nommer un composant de la documentation comme composant ROOT, qui sert alors d’accès au site de documentation.

La version 2 pouvait déjà gérer des extensions pour Asciidoctor, qui permettaient par exemple d’étendre la génération HTML des contenus. Une extension populaire présente des exemples de différents langages de programmation dans différents onglets. Avec la version 3, une API est désormais disponible pour la première fois afin d’étendre le générateur de site. Les développeurs ont ainsi la possibilité d’adapter la structure du site et de contrôler ou de masquer des contenus.

Grâce à la nouvelle API, l’intégration de possibilités de recherche est également devenue plus simple : Le plug-in Antora-Lunr pour une recherche plein texte côté client, très apprécié dans la version 2, a été migré vers Antora 3 et est disponible dans l’interface utilisateur standard. L’intégration d’une solution SaaS comme la recherche Algolia est également possible, mais n’est toujours pas incluse dans l’UI standard.

Lire aussi

Antora 3 prend en charge les versions 12 à 16 de Node.js pour la génération du site. N’importe quel serveur web peut continuer à héberger le site généré – Node.js n’est pas nécessaire pour cela.

Avec la mise à jour vers Asciidoctor 2, les avertissements et les messages d’erreur pendant le building, par exemple en cas de blocs fermés manquants, contiennent désormais le fichier source et le numéro de ligne, ce qui facilite le dépannage. De même, le générateur de site affiche désormais des messages d’erreur lorsqu’une référence croisée ne mène à rien. Avec la configuration correspondante, les messages peuvent être édités au format JSON, ce qui permet de les traiter de manière automatisée. Si on le souhaite, il est possible d’interrompre la construction en cas d’avertissement ou d’erreur, de sorte que seuls des sites de documentation sans erreur soient publiés.

Autre nouveauté : le support des proxies HTTP pendant la génération de sites, comme cela est toujours nécessaire pour les configurations d’entreprise. Il est ainsi possible d’intégrer des référentiels Git qui ne sont accessibles que via un proxy.

Pour la mise à jour à la version 3, le chapitre « What’s New in Antora 3.0 » fournit un aperçu détaillé et une check-list de mise à jour. Pour les changements résultant de la mise à jour vers Asciidoctor 2, il y a également un aperçu. Pour profiter de toutes les nouvelles fonctionnalités d’Antora, il convient toutefois de mettre à jour le thème UI d’Antora.

Les personnes intéressées par des informations plus détaillées sur la prise en main d’Antora trouveront une aide appropriée dans le chapitre « Install and Run Antora Quickstart ».

La communauté autour d’Antora se rencontre en ligne dans le chat Zulip, où les utilisateurs peuvent poser des questions auxquelles les auteurs ou d’autres utilisateurs répondent ensuite.

Lire aussi

Des fonctions telles que la génération de PDF n’ont pas été intégrées dans la nouvelle version majeure, mais dans le chat de la communauté, on trouve les premiers exemples de la manière dont cela peut être résolu avec des extensions. Il manque encore une vue d’ensemble des différentes extensions qui ont été créées au sein de la communauté. Nous espérons qu’elle sera bientôt complétée dans la documentation d’Antora.

Le générateur de site est utilisé pour la documentation d’un nombre croissant de projets open source – dont Eclipse Che, Debezium, Apache Camel et Couchbase. La prise en charge des symbioses Git, qui permet d’utiliser des exemples de code indépendamment de leur emplacement dans la documentation générée par Antora, rend la version 3.0 intéressante pour encore plus de projets open source.

La tendance à la documentation en tant que code se poursuit et permet aux développeurs et aux rédacteurs techniques de collaborer efficacement avec des outils éprouvés et de fournir des versions de la documentation en même temps que le logiciel.

Plus d'articles