Documentation du fournisseur Terraform

Suivre ce workflow

1. Confirmer la portée et les cibles de documentation.

• Mapper les changements de code aux cibles de doc exactes : index du fournisseur, ressources, sources de données, ressources éphémères, ressources listées, fonctions, ou guides.
• Décider si le contenu doit provenir des descriptions de schéma, des templates, ou des deux.

2. Écrire les descriptions de schéma en premier.

• Ajouter des descriptions précises destinées aux utilisateurs dans les champs de schéma pour que les docs générées restent alignées avec le comportement.
• Garder le libellé spécifique au purpose de l'argument, aux contraintes, aux defaults, et au comportement computed.

3. Ajouter ou mettre à jour les fichiers de template dans docs/.

• Créer uniquement les fichiers qui correspondent aux objets du fournisseur implémentés.
• Utiliser les chemins de template recommandés par HashiCorp :
  • docs/index.md.tmpl
  • docs/data-sources/<name>.md.tmpl
  • docs/resources/<name>.md.tmpl
  • docs/ephemeral-resources/<name>.md.tmpl
  • docs/list-resources/<name>.md.tmpl
  • docs/functions/<name>.md.tmpl
  • docs/guides/<name>.md.tmpl
• Garder les templates focalisés sur la vue d'ensemble et les exemples ; s'appuyer sur les sections générées pour les détails champ par champ.

4. Générer la documentation avec tfplugindocs.

• Préférer les defaults du repository quand ils sont configurés :

  go generate ./...

• Sinon, lancer directement le générateur :

  go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>

• Relancer la génération après chaque édition de schéma ou de template.

5. Valider le markdown généré.

• Vérifier que les fichiers dans docs/ correspondent à l'implémentation actuelle du fournisseur.
• Vérifier que les exemples sont du HCL valide et reflètent les noms actuels des arguments/attributs.
• Vérifier que les sémantiques required/optional/computed dans la doc correspondent au comportement du schéma.

6. Appliquer les règles de publication Registry avant la release.

• Utiliser des tags de version sémantique préfixés avec v (par exemple v1.2.3).
• Créer les tags de release à partir de la branche par défaut.
• Garder terraform-registry-manifest.json à la racine du repository.
• S'attendre à ce que les docs soient versionnées dans Registry et commutables avec le sélecteur de version.

7. Prévisualiser ou dépanner la publication si nécessaire.

• Utiliser le processus de preview HashiCorp pour inspecter les docs rendues avant la release quand le risque de précision est élevé.
• Si des docs manquent dans Registry, vérifier le format du tag, la branche source du tag, la présence du fichier manifest, et le statut de publication du fournisseur.

Appliquer la barre de qualité

• Garder la documentation comportementalement exacte ; ne jamais décrire des arguments ou attributs non supportés.
• Garder les exemples minimaux, réalistes, et exécutables.
• Garder la terminologie et le nommage cohérents dans le fournisseur, les ressources, et les sources de données.
• Éviter de dupliquer les blocs d'arguments/attributs générés dans les templates manuels.
• Garder les changements de doc liés au même PR que les changements de schéma/API quand possible.

Charger les références à la demande

• Lire references/hashicorp-provider-docs.md pour les règles source-backed et les liens officiels.
• Charger uniquement les sections nécessaires pour le changement actuel pour garder le contexte léger.