Documentation

Le module Documentation d'un projet montre les pages markdown d'un dossier du dépôt, et permet de les modifier depuis ERHA. Une page enregistrée repart dans le dépôt : un commit direct sur la branche cible, ou une merge request, selon le mode de livraison du projet. La documentation suit la même règle que le code qu'elle décrit.

ERHA ne stocke aucune page. Le dépôt est la seule source : ce que les agents de documentation écrivent en même temps que le code, ce qu'un développeur modifie dans son éditeur et ce qu'un membre change depuis ERHA sont la même chose, au même endroit.

Configurer le dossier

Dans les réglages du projet, section Composants, chaque composant (sauf une landing page) a un champ « Dossier de documentation ». On y met le chemin du dossier dans le dépôt, par exemple docs ou apps/web/docs. Le chemin est relatif à la racine du dépôt du composant.

Sur un projet de type Application, l'onglet Documentation est présent avant même la configuration : il dit comment renseigner le dossier. Sur un autre type, l'onglet apparaît dès qu'un composant a un dossier.

Les fichiers lus sont les .md et .mdx du dossier et de ses sous-dossiers, jusqu'à quatre niveaux, et au plus quatre-vingts pages. Les fichiers et dossiers qui commencent par un point sont ignorés.

Lire

La liste de gauche montre les pages, groupées par sous-dossier. Le titre d'une page est, dans l'ordre : le champ title de son front matter, son premier titre de niveau un, son nom de fichier. La page choisie s'affiche rendue. L'adresse de la page est dans l'URL : un lien vers une page se partage.

La liste est gardée deux minutes en cache. Le bouton de relecture force une lecture du dépôt.

Modifier

Un administrateur de l'espace voit le bouton Modifier. L'éditeur montre le markdown brut, avec un aperçu rendu. Le texte est enregistré tel quel : rien n'est reformaté.

Un message de commit est proposé (docs: update <fichier>) et peut être remplacé. L'éditeur rappelle ce qui va se passer à l'enregistrement :

• Commit direct : le commit est poussé sur la branche cible. Le lien vers le commit est affiché.
• Merge request : une branche docs/<page>-<suffixe> est créée depuis la branche cible, le commit y est poussé, et une merge request vers la branche cible est ouverte. Le lien vers la merge request est affiché. La branche est supprimée à la fusion.

Si la page a changé dans le dépôt entre son ouverture et l'enregistrement, l'enregistrement est refusé et la page doit être rechargée. Deux personnes ne peuvent pas s'écraser mutuellement.

Créer une page

« Nouvelle page » demande un nom de fichier relatif au dossier, avec l'extension .md, et un contenu. Les sous-dossiers sont acceptés (guide/installation.md). Le nom n'accepte que des lettres, des chiffres, des tirets et des points. La livraison est la même que pour une modification.

Demander à l'agent

« Demander à l'agent » crée une tâche pour l'agent référent du projet. L'agent lit le code, met à jour les pages du dossier de documentation, et livre selon le mode du projet. C'est la façon de faire suivre la documentation au code : une tâche qui change une fonctionnalité peut être suivi d'une tâche qui la documente, ou les deux peuvent être demandés ensemble.

La documentation d'ERHA

Cette documentation est elle-même un dossier markdown du dépôt d'ERHA (web/docs/fr et web/docs/en), édité avec ce module. Une page publiée ici est un fichier de ce dossier : le site et l'éditeur regardent la même source.

Chaque fichier commence par un front matter :

---
title: Titre de la page
description: Une phrase affichée sous le titre.
order: 3
---

order range les pages dans le menu. Le fichier index.md est la page d'accueil. Dans la page de l'API, https://api.erha.ai est remplacé par l'adresse de l'API de l'environnement affiché.