Skip to content

provider-docs: add action documentation guidance - #84

Open
AdamTylerLynch wants to merge 2 commits into
hashicorp:mainfrom
AdamTylerLynch:feat/provider-docs-actions
Open

provider-docs: add action documentation guidance#84
AdamTylerLynch wants to merge 2 commits into
hashicorp:mainfrom
AdamTylerLynch:feat/provider-docs-actions

Conversation

@AdamTylerLynch

@AdamTylerLynch AdamTylerLynch commented Jul 13, 2026

Copy link
Copy Markdown
Contributor

The provider-docs skill covered resources, data sources, ephemeral resources, list
resources, functions, and guides — but not actions, so an agent invoked to
document an action got no guidance, even though the sibling provider-actions skill
points here for the docs workflow.

Verified before writing (sources checked, not assumed):

  • The Terraform Registry docs format supports docs/actions/<action>.md pages
    (developer.hashicorp.com/terraform/registry/providers/docs)
  • tfplugindocs generates action documentation — including scaffolding missing
    action templates — with Terraform v1.14.0+, using
    templates/actions/<action type name>.md[.tmpl] and example files at
    examples/actions/<action_type>/action*.tf (hashicorp/terraform-plugin-docs)

Changes

  • SKILL.md: actions added to the trigger description, the doc-target list, and the
    template-path list (with the v1.14.0+ note), plus a pointer to the new reference
    section for action-page structure
  • references/hashicorp-provider-docs.md: new Action Pages section anchored on
    how terraform-provider-aws documents its actions (website/docs/actions/, 11
    hand-written pages analyzed):
    • # Action: <name> H1 prefix, parallel to # Resource: / # Data Source:
    • Examples must show both the action block and the resource-side
      lifecycle { action_trigger { ... } } wiring — an action example without a
      trigger is not runnable
    • ## Argument Reference for config arguments; no attribute/output section
      (actions produce no state — every AWS action page omits it)
    • Callout conventions while actions are experimental: ~> **Note:** alpha/preview
      disclaimer and !> **Warning:** when the action mutates state Terraform does
      not reconcile (the aws_ec2_stop_instance precedent)
    • release-note:new-action changelog type for repos using go-changelog
    • Notes AWS hand-writes these pages (it predates tfplugindocs action support);
      new providers should generate instead

Verification: scripts/validate-structure.sh passes; two-file diff confined to
the provider-docs skill; no conflicts with the other six branches (none touch
provider-docs).


The follow-up commit also captures the documentation-example conventions requested in #14: examples live in examples/ (one per file, imported via tffile) and must not contain terraform, provider, or output blocks.

@AdamTylerLynch
AdamTylerLynch requested a review from a team as a code owner July 13, 2026 17:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant