Génération du readme au format HTML #2
Assignees
admin-gitea
bbaudouin
bouuul
eliottsb
george-claude
Gile
jopop336
tdumele
toucan_dev
yuhiie
Clear assignees
admin-gitea
bbaudouin
bouuul
eliottsb
george-claude
Gile
jopop336
tdumele
toucan_dev
yuhiie
No Assignees
bbaudouin
bbaudouin
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: public/d-crawler#2
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
En tant que rédacteur assidu de la documentation 🥸,
Je veux que le README au format HTML soit généré automatiquement à partir du README au format Markdown, sans avoir à versionner le fichier HTML,
Afin de ne maintenir qu'une seule source de vérité pour la documentation, éviter les doublons de rédaction et supprimer les risques de divergence entre les versions Markdown et HTML.
Description
Actuellement, les fichiers README au format Markdown et HTML sont maintenus séparément et versionnés dans le dépôt. Cette approche entraîne une duplication des efforts de maintenance et un risque d'incohérence entre les deux formats.
L'objectif est de mettre en place un mécanisme de génération automatique du fichier HTML à partir du fichier Markdown lors du processus de build ou de publication de la documentation. Le fichier HTML devient alors un artefact généré et n'a plus vocation à être versionné dans le dépôt.
Critères d'acceptation
Cas nominal
Étant donné qu'un fichier README.md est présent dans le dépôt,
Lorsque le processus de génération de la documentation est exécuté,
Alors un fichier README.html est généré automatiquement à partir du contenu du fichier Markdown.
Gestion du versionnement
Le fichier README.html n'est plus versionné dans le dépôt Git.
La suppression du fichier versionné n'empêche pas la génération de la documentation.
Fidélité du rendu
Le contenu du fichier HTML reflète fidèlement celui du fichier Markdown.
Les liens, tableaux, images et blocs de code sont correctement convertis.
Maintenance
Toute modification apportée au README.md est automatiquement prise en compte lors de la prochaine génération du HTML.
Aucune modification manuelle du fichier HTML n'est nécessaire.
Règles de gestion
Le fichier Markdown constitue l'unique source de vérité de la documentation.
Le fichier HTML est considéré comme un artefact généré.
Toute évolution de la documentation doit être réalisée exclusivement dans le fichier Markdown.
Hors périmètre
Modification du contenu fonctionnel de la documentation.
Refonte graphique ou changement du style du rendu HTML.
Évolution de l'outil de conversion, hors nécessité technique pour automatiser la génération.
Notes techniques
Intégrer la génération du fichier HTML dans le pipeline de build, de publication ou dans le processus de génération de la documentation existant.
Ajouter le fichier README.html au .gitignore si nécessaire.
Vérifier que les outils consommateurs du fichier HTML continuent de fonctionner avec un fichier généré automatiquement.
Et pourquoi pas mettre à jour directement le wiki en fonction du README.md ?
En principe, un readme est fait pour (et par) les devs car ce sont les instructions d installation et la définition des conventions du projet. Un wiki est plutôt fait pour les users (comment utiliser l'application). Est ce que pour ce projet on souhaite avoir exactement les memes infos entre les markdown et le wiki ?