La documentation du développeur comprend généralement une description dans chaque fichier. Ces descriptions peuvent devenir obsolètes, entraînant de la confusion et des informations incorrectes. Pour éviter cela, vous pouvez automatiser la détection des descriptions obsolètes dans votre documentation en utilisant un peu d'IA et GenAIScript.

Markdown et frontmatter

De nombreux systèmes de documentation utilisent le format markdown pour rédiger la documentation et un en-tête « frontmatter » pour stocker les métadonnées. Voici un exemple de fichier markdown avec frontmatter :

---
title: "My Document"
description: "This is a sample document."
---

# My Document

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

L'objectif est de créer un script qui détecte quand le champ de description dans le frontmatter est obsolète.

Le scénario

GenAIScript est destiné à s'exécuter sur des fichiers et fournit une variable spéciale env.files qui contient la liste des fichiers à analyser. Vous pouvez utiliser cette variable pour inclure les fichiers dans le contexte à l'aide de la fonction def. Nous limitons chaque fichier à 2000 jetons pour éviter d'exploser le contenu des fichiers volumineux.

// Define the file to be analyzed
def("DOCS", env.files, { endsWith: ".md", maxTokens: 2000 })

L'étape suivante consiste à confier une tâche au script. Dans ce cas, vérifiez que les champs de contenu et de description dans le frontmatter correspondent.

// Analyze the content to detect outdated descriptions
$`Check if the 'description' field in the front matter in DOCS is outdated.`

Enfin, nous exploitons la fonctionnalité de génération de diagnostics intégrée pour créer une erreur pour chaque description obsolète.

// enable diagnostics generation
$`Generate an error for each outdated description.`

Exécution dans Visual Studio Code

Une fois ce script enregistré dans votre espace de travail, vous pourrez l'exécuter sur un fichier ou un dossier via le menu contextuel
en sélectionnant Exécuter GenAIScript....

Automation

Vous pouvez exécuter automatiquement cet outil sur vos fichiers de documentation pour identifier les descriptions obsolètes à l'aide du cli.

npx --yes genaiscript run detect-outdated-descriptions **/*.md

Ce script peut être intégré à votre pipeline CI/CD pour automatiser le processus de détection.