bicep docs : la commande qui génère enfin la doc de tes modules Bicep

Un README de module Bicep périmé, c’est le genre de dette technique dont personne ne parle jusqu’au jour où un collègue déploie avec le mauvais paramètre parce que la doc listait encore l’ancienne valeur par défaut. Jusqu’ici, la seule option sérieuse pour éviter ça était le script PowerShell Set-AVMModule maintenu par l’équipe Azure Verified Modules — efficace, mais pensé pour leur propre dépôt, pas pour ton repo Bicep perso. Depuis le 24 septembre 2026, il existe enfin une réponse native côté CLI : bicep docs.

Ce que fait la commande

La commande génère un fichier README.md directement à partir de ton code Bicep, sans que tu aies à écrire la moindre ligne de documentation à la main. Elle extrait et met en forme :

• les métadonnées du module (nom, description, si tu les as renseignées via metadata) ;
• la liste des ressources Azure déployées ;
• un tableau des paramètres avec type, caractère obligatoire ou non, et description ;
• un tableau des outputs ;
• les types exportés, variables et fonctions définies dans le module, quand il y en a.

Elle est disponible dans la Bicep CLI à partir de la version 0.47.16. Vérifie la tienne avec bicep --version avant de te lancer — aucun flag expérimental à activer dans bicepconfig.json, la commande est directement utilisable une fois le binaire à jour.

L’utiliser au quotidien

La syntaxe de base ne demande rien de plus que le chemin du fichier :

bicep docs generate ./main.bicep

Par défaut, elle écrit un README.md à côté du fichier source. Trois options couvrent la quasi-totalité des cas réels :

# Afficher le résultat dans le terminal sans écrire de fichier
bicep docs generate ./main.bicep --stdout

# Choisir précisément le nom et l'emplacement du fichier
bicep docs generate ./main.bicep --outfile docs/README.md

# Traiter tous les modules d'un dépôt en une seule commande
bicep docs generate './modules/**/main.bicep'

Ce dernier exemple avec --pattern est à mon avis le plus intéressant des trois : il transforme la commande en étape de pipeline. Tu peux l’ajouter dans un job GitHub Actions qui tourne à chaque pull request touchant un fichier .bicep, et faire échouer le build si le README généré diverge de celui commité — exactement le même principe qu’un terraform fmt -check, mais pour la documentation.

Personnaliser le format avec Scriban

Le README par défaut ne te plaît pas tel quel ? La génération repose sur Scriban, un langage de templating léger déjà utilisé ailleurs dans l’écosystème .NET. Tu peux fournir ton propre modèle via bicepconfig.json :

{
  "documentation": {
    "template": {
      "file": "templates/readme.scriban"
    }
  }
}

Et injecter des valeurs supplémentaires dans le template avec --custom-template-value (pour une valeur isolée) ou --custom-template-value-file-path (pour un lot de valeurs depuis un fichier). De quoi, par exemple, ajouter automatiquement un lien vers ton wiki interne ou un badge de statut de pipeline en haut de chaque README généré.

Le point qu’il ne faut pas perdre de vue

La fonctionnalité est encore marquée comme expérimentale par Microsoft. Ça ne veut pas dire qu’elle est buguée — elle fonctionne bien dans mes tests — mais que les noms d’options, la structure du bicepconfig.json et le modèle de template par défaut peuvent changer d’une version à l’autre sans garantie de compatibilité ascendante. Si tu l’intègres dans un pipeline de CI, épingle la version de la Bicep CLI que tu utilises plutôt que de pointer vers la dernière disponible, histoire d’éviter qu’un README généré change de structure sans prévenir un lundi matin.

Pour un module publié publiquement ou partagé entre plusieurs équipes, je recommande clairement d’adopter la commande maintenant : le gain de cohérence dépasse largement le risque de devoir ajuster deux ou trois options dans six mois. Pour un module strictement interne et peu réutilisé, tu peux attendre que la fonctionnalité sorte de son statut expérimental sans rien perdre.

FAQ

Est-ce que ça remplace Set-AVMModule pour les modules Azure Verified Modules ?

Pas entièrement pour l’instant. Le script Set-AVMModule gère aussi la validation de la structure de dossiers et la compilation du template, en plus du README. bicep docs ne fait que la partie documentation, mais le fait nativement, sans dépendance à un script PowerShell externe.

La commande fonctionne-t-elle aussi via Azure CLI (az bicep) ?

Au moment de la rédaction, bicep docs n’apparaît pas encore dans la liste des sous-commandes az bicep documentées officiellement. Utilise directement le binaire Bicep CLI autonome en attendant une éventuelle intégration.

Que se passe-t-il si mon module utilise des imports compile-time ou des types définis par l’utilisateur ?

Ces éléments activent la génération de code en langageVersion 2.0, ce qui n’empêche pas bicep docs de fonctionner — les types exportés sont justement l’une des sections que la commande documente. On en parlait d’ailleurs en détail dans notre article sur les types définis par l’utilisateur en Bicep.

Pour aller plus loin

Si tu gères une bibliothèque de modules Bicep internes sur le modèle des Azure Verified Modules, bicep docs est le genre de petit outil qui change vraiment le quotidien une fois automatisé dans la CI. Notre article sur le passage aux Azure Verified Modules explique pourquoi cette discipline de documentation compte autant que le code lui-même dès que plusieurs équipes consomment les mêmes modules. Installe la dernière Bicep CLI, lance bicep docs generate sur ton dépôt existant, et regarde ce qui en sort — il y a de bonnes chances que tu découvres au passage un paramètre que personne n’avait documenté depuis des mois.