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 dossiercontent/{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) :
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.
Prévisualisation
Pour prévisualiser la documentation de la version courante, MkDocs fournit un serveur local :
À 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 :
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 :
À 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 :
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.