Documenter

Architecture

Organisation

La documentation a vocation à couvrir le plus exhaustivement possible les aspects suivants de Hiboo :

• Comment se servir de Hiboo en tant qu'utilisateurice ?
• Comment administrer une instance ?
• Comment contribuer au projet ?

Arborescence

docs
├── config
│   ├── base.yml
│   ├── en.yml
│   ├── fr.yml
│   └── pages.yml
├── content
│   ├── assets
│   ├── en
│   └── fr
│       ├── admin
│       │   ├── concepts.md
│       │   ├── index.md
│       │   ├── install.md
│       │   ├── services.md
│       │   └── users.md
│       ├── assets -> ../assets
│       ├── CHANGELOG.md -> ../../../CHANGELOG.md
│       ├── contrib
│       ├── index.md
│       └── user

Configuration

La documentation de Hiboo est écrite en markdown (.md) et générée avec Mkdocs. Les fichiers markdown servent à publier deux versions de la documentation : l'une est embarquée dans l'application (hiboo.tld/docs), l'autre est autonome et déployée sur hiboo.acides.org.

Pour ce faire, le dossier docs/config/ comporte plusieurs fichiers de configuration Mkdocs :

• base.yml : paramètres partagés entre les déploiements.
• {langage}.yml : paramètres spécifiques à la version embarquée (un fichier par langage).
• pages.yml : paramètres spécifiques à la version autonome publiée sur hiboo.acides.org avec GitLab Pages.

Note : le dossier templates/ est un thème utilisé uniquement par la version embarquée dans Hiboo.

Contenu

Le dossier content/ est celui où est écrite la documentation à proprement parler :

• content/{langage}/ contient les documents pour une langue donnée.
• assets/img/ contient les images utilisées dans la documentation. Ce dossier est répliqué en tant que lien symbolique dans chaque dossier content/{langage}/ afin de pouvoir utiliser des ressources communes sans avoir à les dupliquer réellement.

Attention : peu importe le langage, les noms des fichiers pour les pages sont toujours en anglais, et ce afin de veiller plus facilement à l'homogénéité du contenu entre les langues.

Écrire de la documentation

Pour contribuer à la documentation, le mieux est de commencer par la lire attentivement pour vérifier la pertinence de ce qu'on veut y modifier. Il faut ensuite s'assurer qu'on dispose des outils nécessaires pour le développement local (si les modifications sont mineures, il est possible d'utiliser l'éditeur intégré à la forge Gitlab). Enfin, il faut garder en tête quelques principes :

• On revient à la ligne à 80 caractères.
• La documentation doit être très majoritairement textuelle et descriptive. Elle ne doit pas s'appuyer sur des captures d'écran (des éléments graphiques de type schémas peuvent être pertinents).
• Il est admis que les termes techniques anglais n'ont pas toujours vocation à être traduits dans les autres langues (par exemple merge request). Dans ce cas, on peut les mettre en italique.
• Il faut veiller à mettre des liens internes dès qu'on fait référence à d'autres parties de la documentation.

Attention : Les modifications de mise en page et de la structure doivent rester compatible pour la version intégrée ainsi que la version autonome.

Compiler la documentation en local

Version embarquée

Dans l'environnement de développement, à la racine de l'application ou depuis le shell du container, exécuter (par exemple pour compiler la version française de la documentation) :

poetry run mkdocs build -f docs/config/fr.yml

Version autonome

Le contenu de cette documentation est le même que pour celle embarquée, mais le thème utilisé est Material for MkDocs, et elle a vocation à être déployée avec GitLab Pages sur hiboo.acide.org avec les différentes versions.

Dépendences

La documentation en ligne nécessite d'installer des dépendances supplémentaires comme le thème Material for MkDocs, et d'autres.

poetry install --with docs

Prévisualisation

Pour prévisualiser la documentation de la version courante, MkDocs fournit un serveur local :

poetry run mkdocs serve -f docs/config/pages.yml

À l'intérieur d'un nœud Podman ou Docker, il peut être nécessaire de servir sur toute l'interface du container afin d'y accéder depuis l'hôte sur localhost :

poetry run mkdocs serve -f docs/config/pages.yml -a 0.0.0.0:8000

Versionnage

La gestion des versions est assurée par Mike, dans la branche dédiée pages. Mike crée des commits des fichiers statiques générés avec MkDocs dans la branche pages pour chaque version publiée. Quand une version est publiée, en théorie elle n'est jamais modifiée part la suite, ce qui permet de la laisser intacte même avec une nouvelle version de Mkdocs ou Mike qui pourrait faire échouer la compilation.

Il est aussi possible d'utiliser Mike pour prévisualiser toutes les versions présentes dans la branche pages avec un serveur local :

poetry run mike serve --config-file docs/config/pages.yml --branch pages

À l'intérieur d'un nœud Podman ou Docker, il peut être nécessaire de servir sur toute l'interface du container afin d'y accéder depuis l'hôte sur localhost :

poetry run mike serve --config-file docs/config/pages.yml --branch pages -a 0.0.0.0:8000

Compilation

Pour compiler une nouvelle version de la documentation, il faut donc faire appel à la sous commande deploy de Mike en précisant la version à mettre à jour.

S'il s'agit de la dernière version en date, on ajoute l'alias latest qui, une fois en ligne, redirigera par défaut vers la dernière version de la documentation.

poetry run mike deploy --config-file docs/config/pages.yml --branch pages --update-aliases 0.3.x latest

Attention : On considère que les versions de patch de Hiboo ne nécessitent pas une nouvelle version de la documentation, mais juste une mise à jour. Les numéros de version dans la documentation sont ainsi de la forme <major>.<minor>.x, par exemple 0.3.x.

Déploiement

Une fois la nouvelle documentation compilée, il est possible de la mettre en ligne en poussant la branche pages vers le répertoire d'origine. Un CI GitLab s'occupe de mettre en ligne la documentation avec GitLab Pages.

Il est possible de demander à Mike de pousser les modifications au moment de la compilation (cela ne permet en revanche pas de vérifier que tout est ok avant de push).

poetry run mike deploy --push --config-file docs/config/pages.yml --branch pages --update-aliases 0.3.x latest

Info : La branche pages est protégée, seuls les comptes avec le rang maintainer ont le droit d'y pousser des modifications. En revanche, il est possible de faire une merge request vers cette branche.