modifié le

Eléments constitutifs

Un site

Un site Antora c’est :

  • des meta-données décrivant le site (un playbook YAML),

  • un ensemble de components, qui constituent le fond documentaire du site,

  • un look (UI), implémentant le rendu.

Antora sépare strictement le contenu du rendu.

Il existe un catalogue d’UI pour Antora. Tous les components d’un site prennent le look défini par l’UI associée à ce site. Un composant intégré dans différents sites prendra donc pour chacun d’eux le look de son site (autrement dit, il n’y a aucune notion de rendu dans un component).

Dans cette démo, le site est l’ensemble des supports de cours dispensés par l’auteur à une promotion donnée (promotion=filière+année). Si l’auteur intervient dans plusieurs promos (par exemple en licence informatique, licence pro développement web et master datascience), alors chacune d’elles aura son site propre.

L’UI utilisé est l’Antora Default UI.

Il n’y a pas de système de navigation géré au niveau d’un site.

La page d’accueil de ce site de démo est un aiguillage vers les components de ce site. Cette page AsciiDoctor a été faite à la main, comme une simple liste de liens :

= Master Data Science

Index des supports de cours (factices) du master Data Science::

* xref:C:ROOT:index.adoc[Programmation C]
* xref:apache:ROOT:index.adoc[Apache]
* xref:genie_logiciel::index.adoc[]
* xref:python_objet:ROOT:index.adoc[]

Le making of::

* xref:makingof:ROOT:index.adoc[Supports de cours avec Antora]
* xref:En@makingof:ROOT:index.adoc[Course materials with Antora]

Component

Un component est un sujet traité (ici, un support de cours). Concrètement, c’est un repository git contenant des documents interconnectés et autosuffisants. Il est défini par un playbook nommé antora.yml.

Bien que les components d’un site soient indépendants les uns des autres, des liens de l’un peuvent néanmoins renvoyer vers des pages d’un autre.
Example 1. genie_logiciel/antora.yml

Le playbook antora.yml du component genie_logiciel est :

name: genie_logiciel
title: Génie logiciel
version: 2022
start_page: ROOT:index.adoc
nav:
- nav.adoc

Un component est auto-suffisant. En tant que repository git, il possède son propre historique, ses versions successives, etc.

Pour l’étudiant, un component est identifiable dans l’URL, dont la forme est "site/component/version/…​".

Les components de ce site de démo sont master, C, apache, genie_logiciel, python_objet et making_of, labellisés respectivement comme Master Data Science, Programmation en C, Serveur Apache, Génie logiciel et Python Objet et Making Of..

Un component possède sa propre navigation.

Dans le site de démo, la navigation du component genie_logiciel est un fichier nav.adoc contenant une liste à plusieurs niveaux :

* xref::intro.adoc[]
* xref::processus.adoc[Processus de développement]
* xref::fortran.adoc[]
* xref::python.adoc[]

* Problème
** xref:probleme:sujet.adoc[Sujet]
** xref:probleme:solution.adoc[Solution]

Un site peut assembler plusieurs versions d’un même component. En jouant astucieusement avec git, on peut coupler des différentes version d’un component au branche du repository correspondant.

Dans le site, on remarque différentes versions relatives à l’année (2020, 2021, 2022, ainsi que en cours et -). Ces versions correspondent effectivement à des branches git. Mais on verra plus loin que ce ne sont pas seules versions existantes.

Un component est structuré en modules.

Module

Un module est un ensemble de fichiers logiquement liés entre eux. On y trouve des fichiers sources *.adoc (répertoire pages), les images incluses dans ces pages (répertoire images), des fichiers destinés à être téléchargés depuis ces pages, comme des documents PDF, des exemples de codes sources, etc. (répertoire assets/attachments et examples), ainsi que des portions de pages sources (répertoire partials). Physiquement, un module est une sous-arborescence de répertoires du component. Contrairement à un component qui possède une existance indépendante du site qui le publie, un module n’a pas pas d’existence propre en dehors du component auquel il contribue. C’est juste un moyen d’organiser le component.

Pour l’étudiant, un component est identifiable dans l’URL, dont la forme est "site/component/version/module/…​".

On peut définir une navigation au niveau d’un module. Donc différentes stratégie sont possibles :

  • gérer la navigation d’un component en un fichier unique,

  • gérer la navigation au niveau de chaque module, et aggréger (avec des include) ces fichiers de navigation au niveau du component,

  • mixer les 2.