diff --git a/terraform/provider-development/skills/provider-docs/SKILL.md b/terraform/provider-development/skills/provider-docs/SKILL.md index d681cae..22b9214 100644 --- a/terraform/provider-development/skills/provider-docs/SKILL.md +++ b/terraform/provider-development/skills/provider-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: provider-docs -description: Create, update, and review Terraform provider documentation for Terraform Registry using HashiCorp-recommended patterns, tfplugindocs templates, and schema descriptions. Use when adding or changing provider configuration, resources, data sources, ephemeral resources, list resources, functions, or guides; when validating generated docs; and when troubleshooting missing or incorrect Registry documentation. +description: Create, update, and review Terraform provider documentation for Terraform Registry using HashiCorp-recommended patterns, tfplugindocs templates, and schema descriptions. Use when adding or changing provider configuration, resources, data sources, ephemeral resources, list resources, functions, actions, or guides; when validating generated docs; and when troubleshooting missing or incorrect Registry documentation. --- # Terraform Provider Docs @@ -8,7 +8,7 @@ description: Create, update, and review Terraform provider documentation for Ter ## Follow This Workflow 1. Confirm scope and documentation targets. -- Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, or guides. +- Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, actions, or guides. - Decide whether content should come from schema descriptions, templates, or both. 2. Write schema descriptions first. @@ -24,8 +24,11 @@ description: Create, update, and review Terraform provider documentation for Ter - `docs/ephemeral-resources/.md.tmpl` - `docs/list-resources/.md.tmpl` - `docs/functions/.md.tmpl` + - `docs/actions/.md.tmpl` (tfplugindocs generates action docs with Terraform v1.14.0+) - `docs/guides/.md.tmpl` - Keep templates focused on overview and examples; rely on generated sections for field-by-field details. +- Keep HCL examples in the `examples/` directory — one example per file, pulled into templates with `tffile` — rather than inlined in templates (see Example File Conventions in `references/hashicorp-provider-docs.md`). Examples must not contain `terraform`, `provider`, or `output` blocks. +- For action pages, follow the structure in `references/hashicorp-provider-docs.md` (Action Pages section): examples must show both the `action` block and the `action_trigger` lifecycle wiring, and actions get no attribute/output section. 4. Generate documentation with `tfplugindocs`. - Prefer repository defaults when configured: diff --git a/terraform/provider-development/skills/provider-docs/references/hashicorp-provider-docs.md b/terraform/provider-development/skills/provider-docs/references/hashicorp-provider-docs.md index 559e486..453fdd3 100644 --- a/terraform/provider-development/skills/provider-docs/references/hashicorp-provider-docs.md +++ b/terraform/provider-development/skills/provider-docs/references/hashicorp-provider-docs.md @@ -20,8 +20,40 @@ Use these template paths when the corresponding provider objects exist: - `docs/ephemeral-resources/.md.tmpl` - `docs/list-resources/.md.tmpl` - `docs/functions/.md.tmpl` +- `docs/actions/.md.tmpl` - `docs/guides/.md.tmpl` +The Registry renders action pages from `docs/actions/.md`, and +`tfplugindocs` generates action documentation (including missing template +scaffolds) with Terraform v1.14.0+. Action example files follow the +convention `examples/actions//action*.tf`. + +## Example File Conventions + +Keep example HCL in the `examples/` directory and pull it into templates, +instead of inlining HCL in `.tmpl` files: + +``` +examples/ +├── provider/provider.tf # provider block for the index page only +├── resources//resource.tf # picked up by generated templates +├── data-sources//data-source.tf +└── actions//action.tf +``` + +- **One example per file**, referenced from templates with + `{{ tffile "examples/resources/examplecloud_widget/resource.tf" }}` — + named variants get their own files (`resource-with-tags.tf`), each behind + its own heading in the template. +- **No `terraform`, `provider`, or `output` blocks** in resource, data + source, or action examples. Version constraints and provider + configuration belong on the provider index page only; outputs distract + from the object being documented. (The one exception is + `examples/provider/provider.tf`, which exists to show provider + configuration.) +- Keep each example minimal, runnable, and formatted with + `terraform fmt` — generated docs render the file verbatim. + ## Generation Workflow HashiCorp recommends wiring generator execution through `go generate`: @@ -42,6 +74,53 @@ Alternative direct execution: go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name ``` +## Action Pages + +Structure modeled on the largest production example, terraform-provider-aws +(`website/docs/actions/` — hand-written there because that provider predates +`tfplugindocs` action support; new providers should generate instead): + +- One page per action. H1 uses an `Action:` prefix — `# Action: examplecloud_restart_widget` — + parallel to `# Resource:` / `# Data Source:` on sibling pages. +- Intro paragraph states what the action does and whether it is synchronous + or asynchronous, then links to the upstream service documentation for the + operation it invokes. +- `## Example Usage` starts with `### Basic Usage` and must show **both** + halves of using an action: the `action` block and the resource-side + `lifecycle { action_trigger { ... } }` wiring — an action example without a + trigger is not runnable: + + ```terraform + action "examplecloud_restart_widget" "example" { + config { + widget_id = examplecloud_widget.example.id + } + } + + resource "terraform_data" "trigger" { + lifecycle { + action_trigger { + events = [after_create, after_update] + actions = [action.examplecloud_restart_widget.example] + } + } + } + ``` + +- `## Argument Reference` lists `config` arguments (either flat, or split + into required/optional groups). **No attribute/output reference section** — + actions produce no state, and including one misleads readers. +- Callout conventions (while actions remain experimental): + - `~> **Note:**` for the preview disclaimer, e.g. "`` is in alpha. + Its interface and behavior may change as the feature evolves, and + breaking changes are possible." + - `!> **Warning:**` when the action causes changes Terraform does not + reconcile (e.g. it mutates a resource whose state attributes will be + stale until the next refresh) — name the affected attribute and the + consequence. +- If the repo tracks release notes with go-changelog, new actions use the + `release-note:new-action` entry type. + ## Release and Publication Constraints - Use semantic version tags prefixed with `v`.