Maintenir un livre de documentation dont les exemples de code sont testés comme du vrai code

## Traiter chaque bloc de code du livre comme du code testé, pas comme du simple texte Le livre est un ensemble d'exemples pratiques rédigés sous forme de fichiers markdown contenant des blocs de code intégrés. Un harnais de tests de documentation parcourt l'arborescence des sources, extrait chaque bloc de code, le compile et l'exécute : un exemple cassé fait donc échouer la compilation exactement comme du code applicatif cassé. ### Ce que cela implique pour chaque modification Un exemple qui ne compile pas n'est pas de la documentation. La prose peut être reformulée librement, mais toute modification à l'intérieur d'un bloc de code est une modification de code source testé et doit passer par la commande de test avant d'être proposée. ### Garder le livre rendu et la surface de test synchronisés Le même markdown alimente le livre rendu et le harnais de tests : les choix de mise en forme portent donc du sens. Les annotations posées sur un bloc de code déterminent la façon dont le harnais le traite, et les lignes masquées aux lecteurs sont malgré tout compilées. Ne supprimez jamais une annotation ou une ligne masquée dans le seul but de rendre la page affichée plus propre. ## Construire, tester et afficher le livre avec les commandes documentées Faites passer chaque action courante par les commandes documentées plutôt que d'inventer des invocations improvisées, afin que les exécutions locales correspondent à l'intégration continue. ### Les commandes qui comptent - Construire le livre à partir des sources markdown. - Lancer la suite complète, c'est-à-dire les tests de documentation plus la passe de vérification orthographique. - Lancer uniquement la cible des tests de documentation quand vous avez modifié un bloc de code et que vous voulez la boucle rapide. - Servir le livre en local avec rechargement à chaud pendant l'édition de la prose. - Construire et tester ensemble, comme comportement par défaut avant la revue. - Lancer le vérificateur de liens, qui valide les liens internes et externes par rapport à un fichier de configuration versionné. - Lancer le script de vérification orthographique en mode interactif et ajouter les nouveaux mots légitimes au fichier dictionnaire du dépôt, afin que cet ajout soit relu en même temps que la modification. ### Figer la chaîne d'outils Le générateur de livre et le vérificateur de liens sont installés à des versions figées exactes, via une seule commande d'installation documentée. Ne mettez pas à jour un outil en local pour contourner un échec : une dérive de version transforme un échec reproductible en un échec que vous êtes seul à voir. ## Connaître les deux façons de ranger les exemples et ne pas monter les versions des bibliothèques partagées Les exemples sont testés de l'une ou l'autre de deux manières, et savoir quel modèle un fichier utilise détermine où vivent son code et ses dépendances. ### Modèle un : blocs en ligne testés sur place Les blocs de code se trouvent directement dans le markdown, sous l'arborescence des sources. Un script de build parcourt cette arborescence à la recherche de fichiers markdown et génère un test par bloc de code. Toute dépendance dont un tel exemple a besoin doit déjà exister dans le manifeste racine. Les blocs acceptent des annotations pour l'édition du langage et pour des comportements comme compilation seule, panique attendue et ignoré ; le code d'habillage dont les lecteurs n'ont pas besoin s'écrit sous forme de lignes préfixées par un dièse et une espace, que le harnais compile mais que le livre rendu masque. C'est le modèle historique : il reste fonctionnel, mais on ne l'étend plus. ### Modèle deux : paquets autonomes inclus dans le markdown Le code vit dans son propre paquet, sous un répertoire de code partagé, avec un manifeste indépendant, et le markdown l'intègre via une directive d'inclusion qui pointe vers le fichier source par chemin relatif. Les inclusions par plage de lignes permettent à une page de n'afficher qu'une partie d'un fichier, ce qui est la façon de garder l'échafaudage de test hors de l'exemple rendu. Le chemin est exclu du harnais de tests de documentation dans le script de build, afin que le code ne soit pas testé deux fois. C'est le modèle à privilégier pour les exemples nouveaux et migrés. ### La règle sur les dépendances Ne modifiez pas les versions des dépendances dans le manifeste racine. Le manifeste racine est partagé par tous les exemples en ligne : une montée de version destinée à satisfaire une seule page peut donc en casser des dizaines d'autres en silence. Quand un exemple a besoin d'une dépendance plus récente, migrez plutôt cet exemple vers un paquet autonome doté de ses propres versions figées. ## Déplacer dans son propre paquet l’exemple qui a besoin d’une bibliothèque plus récente Quand une version de dépendance doit changer, convertissez les exemples concernés en paquets autonomes. Suivez les étapes dans l'ordre, car chacune laisse le dépôt dans un état dont dépend l'étape suivante. 1. Créez le paquet sous le répertoire de code partagé, dans un dossier nommé d'après sa catégorie puis d'après l'exemple, avec son propre manifeste. Héritez des dépendances partagées de l'espace de travail lorsque c'est possible, ou figez les versions indépendamment lorsque l'objectif même est de diverger. 2. Sortez le code du bloc de code markdown pour le placer dans les sources du paquet : un binaire par exemple exécutable, ou un module de bibliothèque pour les exemples de type bibliothèque. 3. Enregistrez le paquet dans la liste des membres de l'espace de travail, dans le manifeste racine. 4. Remplacez le code en ligne du markdown par une directive d'inclusion dont le chemin relatif part de l'emplacement du fichier markdown lui-même pour aller jusqu'aux sources du paquet. 5. Excluez le chemin migré du harnais de tests de documentation dans le script de build. Il existe deux listes d'exclusion : l'une prend un préfixe de répertoire et retire tout ce qui se trouve dessous, l'autre prend un seul fichier markdown. Utilisez la plus étroite qui convient. 6. Testez des deux côtés : lancez les tests propres au nouveau paquet, et relancez la cible des tests de documentation pour confirmer que la suppression du bloc n'a pas cassé les exemples en ligne restants. Une migration qui s'arrête avant l'étape cinq laisse l'exemple compilé deux fois, et une migration qui s'arrête avant l'étape six peut faire disparaître de la couverture en silence. ## Lire les fichiers qui décident de ce qui est construit et testé Une poignée de fichiers décide de ce qui est testé, de ce qui est rendu et des commandes qui existent. Lisez-les avant de modifier un comportement, et modifiez-les de façon délibérée. - Le manifeste racine contient les dépendances utilisées par les exemples en ligne ainsi que la liste des membres de l'espace de travail. - Le script de build découvre le markdown destiné au harnais de tests de documentation et porte les deux listes d'exclusion qui empêchent les exemples migrés d'être testés deux fois. - Le fichier de configuration du livre contrôle la façon dont le markdown est rendu en livre. - La configuration de l'outil de build définit l'alias du lanceur de tâches sur lequel reposent les commandes documentées. - Le paquet du lanceur de tâches implémente la construction, les tests et la vérification des liens sous forme de sous-commandes, si bien que la même logique sert à la fois à un contributeur et à l'intégration continue. Si une commande se comporte autrement que ce qui est décrit ici, considérez les fichiers ci-dessus comme la source de vérité et corrigez la description au lieu de la contourner. ## Écrire des exemples complets que le lecteur peut copier et exécuter Un exemple se juge à la possibilité pour quelqu'un de le copier dans son propre projet et de le voir fonctionner, non à sa brièveté sur la page. ### Règles de contenu - Les exemples sont complets et compilables, pas des fragments. - Propagez les erreurs avec l'opérateur de propagation d'erreurs du langage plutôt que de paniquer en cas d'échec, et suivez le motif de gestion d'erreurs documenté par le projet. - Évitez les imports globaux, pour qu'un lecteur voie exactement de quels traits et de quels éléments l'exemple dépend. - Marquez en compilation seule les exemples qui nécessitent un service externe ou un accès réseau, afin que la suite reste exécutable hors ligne. - Masquez le code d'habillage à l'aide du préfixe de ligne masquée plutôt que de le supprimer, afin que l'exemple compile toujours. - Préférez créer un paquet autonome pour un nouvel exemple plutôt que d'ajouter une dépendance supplémentaire au manifeste racine. ### Ajouter une nouvelle section de premier niveau Lorsque vous ajoutez une page de section de premier niveau, ajoutez aussi une inclusion vers elle dans la page de table des matières du livre, à la bonne position alphabétique. Cette page est le point d'entrée du lecteur, et une section qui n'y est pas incluse est de fait invisible, même si elle se construit sans erreur. ## Réussir tous les tests et la liste de contrôle avant de demander une revue Vérifiez tous les points suivants avant d'ouvrir ou de mettre à jour une modification en revue, puis de nouveau après toute réécriture. - La suite de tests complète passe en local, en utilisant la commande documentée qui lance tous les tests plutôt qu'une exécution partielle. - Les commits sont regroupés en un seul et rebasés sur la dernière version de la branche principale. - La description contient une clause de fermeture de ticket correcte, ou bien cette clause est entièrement retirée lorsqu'aucun ticket n'existe. Un mauvais numéro de ticket est pire que pas de numéro du tout. - Les listes non rendues sont triées : liens, références, identifiants et entrées de manifeste. C'est l'ordre trié qui garde petits les diffs futurs. - Les liens de documentation vers des pages de référence d'API externes utilisent le segment de version générique au lieu d'une version figée, afin que le lien ne se périme pas à la prochaine publication. - L'exemple utilise la gestion d'erreurs standard du projet, sans raccourci de panique en cas d'échec. - Les identifiants de code présents dans la description sont écrits comme des noms entre accents graves, hyperliés vers leurs pages de référence via des définitions de liens placées en bas du fichier. Après soumission, surveillez l'exécution d'intégration continue et corrigez tout échec qu'elle signale, plutôt que de laisser une modification en rouge à trier par un relecteur.