Skip to content

Commit 65ddd34

Browse files
austinvalledependabot[bot]hc-github-team-tf-provider-devex
authored
Add support for generating documentation for actions (#505)
* update go mod to use new tfjson PR * add generate command * add action log messages to allow tests to pass * add generate tests * validate command and tests * add migrate support + tests * add unit tests * update readme * add TBD changelogs * update changelogs * build(deps): bump github.com/hashicorp/terraform-json (#506) Bumps [github.com/hashicorp/terraform-json](https://github.com/hashicorp/terraform-json) from 0.25.0 to 0.26.0. - [Release notes](https://github.com/hashicorp/terraform-json/releases) - [Commits](hashicorp/terraform-json@v0.25.0...v0.26.0) --- updated-dependencies: - dependency-name: github.com/hashicorp/terraform-json dependency-version: 0.26.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * [CI] Update lock workflow file * build(deps): bump the github-actions group with 2 updates (#507) Bumps the github-actions group with 2 updates: [actions/checkout](https://github.com/actions/checkout) and [goreleaser/goreleaser-action](https://github.com/goreleaser/goreleaser-action). Updates `actions/checkout` from 4.2.2 to 5.0.0 - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@11bd719...08c6903) Updates `goreleaser/goreleaser-action` from 6.3.0 to 6.4.0 - [Release notes](https://github.com/goreleaser/goreleaser-action/releases) - [Commits](goreleaser/goreleaser-action@9c156ee...e435ccd) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 5.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: github-actions - dependency-name: goreleaser/goreleaser-action dependency-version: 6.4.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: github-actions ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * build(deps): bump github.com/zclconf/go-cty from 1.16.3 to 1.16.4 (#514) Bumps [github.com/zclconf/go-cty](https://github.com/zclconf/go-cty) from 1.16.3 to 1.16.4. - [Release notes](https://github.com/zclconf/go-cty/releases) - [Changelog](https://github.com/zclconf/go-cty/blob/main/CHANGELOG.md) - [Commits](zclconf/go-cty@v1.16.3...v1.16.4) --- updated-dependencies: - dependency-name: github.com/zclconf/go-cty dependency-version: 1.16.4 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * build(deps): bump github.com/hashicorp/terraform-exec (#515) Bumps [github.com/hashicorp/terraform-exec](https://github.com/hashicorp/terraform-exec) from 0.23.0 to 0.23.1. - [Release notes](https://github.com/hashicorp/terraform-exec/releases) - [Changelog](https://github.com/hashicorp/terraform-exec/blob/main/CHANGELOG.md) - [Commits](hashicorp/terraform-exec@v0.23.0...v0.23.1) --- updated-dependencies: - dependency-name: github.com/hashicorp/terraform-exec dependency-version: 0.23.1 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * update go mod * update go sum * update to use main of tfjson --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Service Account - Terraform Provider DevEx <100357958+hc-github-team-tf-provider-devex@users.noreply.github.com>
1 parent 52c4380 commit 65ddd34

File tree

43 files changed

+1603
-19
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1603
-19
lines changed

‎.changes/unreleased/FEATURES-20250811-174112.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
kind: FEATURES
2+
body: 'generate: Add support for unlinked actions'
3+
time: 2025-08-11T17:41:12.858383-04:00
4+
custom:
5+
Issue: "505"

‎.changes/unreleased/FEATURES-20250811-174141.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
kind: FEATURES
2+
body: 'migrate: Add support for unlinked actions'
3+
time: 2025-08-11T17:41:41.553344-04:00
4+
custom:
5+
Issue: "505"

‎.changes/unreleased/FEATURES-20250811-174155.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
kind: FEATURES
2+
body: 'validate: Add support for unlinked actions'
3+
time: 2025-08-11T17:41:55.966547-04:00
4+
custom:
5+
Issue: "505"

‎README.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,7 @@ When you run `tfplugindocs`, by default from the root directory of a provider co
117117
* Generate data source template files, if missing
118118
* Generate function template files, if missing (Requires Terraform v1.8.0+)
119119
* Generate ephemeral resource template files, if missing (Requires Terraform v1.10.0+)
120+
* Generate action template files, if missing (Requires Terraform v1.14.0+)
120121
* Copy all non-template files to the output website directory
121122
122123
> [!NOTE]
@@ -207,10 +208,12 @@ For templates:
207208
|--------------------------------------------------------------------|-----------------------------------------------|
208209
| `templates/` | Root of templated docs |
209210
| `templates/index.md[.tmpl]` | Docs index page (or template) |
211+
| `templates/actions.md[.tmpl]` | Generic action page (or template) |
212+
| `templates/actions/<action type name>.md[.tmpl]` | Action page (or template) |
210213
| `templates/data-sources.md[.tmpl]` | Generic data source page (or template) |
211214
| `templates/data-sources/<data source name>.md[.tmpl]` | Data source page (or template) |
212215
| `templates/ephemeral-resources.md[.tmpl]` | Generic ephemeral resource page (or template) |
213-
| `templates/ephemeral-resources/<ephemeral resource name>.md[.tmpl]` | Ephemeral resource page (or template) |
216+
| `templates/ephemeral-resources/<ephemeral resource name>.md[.tmpl]`| Ephemeral resource page (or template) |
214217
| `templates/functions.md[.tmpl]` | Generic function page (or template) |
215218
| `templates/functions/<function name>.md[.tmpl]` | Function page (or template) |
216219
| `templates/resources.md[.tmpl]` | Generic resource page (or template) |
@@ -227,6 +230,7 @@ For examples:
227230
|---------------------------------------------------------------------------|--------------------------------------------|
228231
| `examples/` | Root of examples |
229232
| `examples/provider/provider.tf` | Provider example config |
233+
| `examples/actions/<action_type>/action.tf` | Action example config |
230234
| `examples/data-sources/<data source name>/data-source.tf` | Data source example config |
231235
| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config |
232236
| `examples/functions/<function name>/function.tf` | Function example config |
@@ -249,6 +253,7 @@ Legacy website directory structure:
249253
| `website/` | Root of website docs |
250254
| `website/docs/guides` | Root of guides subdirectory |
251255
| `website/docs/index.html.markdown` | Docs index page |
256+
| `website/docs/actions/<action type name>.html.markdown` | Action page |
252257
| `website/docs/d/<data source name>.html.markdown` | Data source page |
253258
| `website/docs/ephemeral-resources/<ephemeral resource name>.html.markdown` | Ephemeral resource page |
254259
| `website/docs/functons/<function name>.html.markdown` | Functions page |
@@ -261,6 +266,7 @@ Docs website directory structure:
261266
| `docs/` | Root of website docs |
262267
| `docs/guides` | Root of guides subdirectory |
263268
| `docs/index.html.markdown` | Docs index page |
269+
| `docs/actions/<action type name>.html.markdown` | Action page |
264270
| `docs/data-sources/<data source name>.html.markdown` | Data source page |
265271
| `docs/ephemeral-resources/<ephemeral resource name>.html.markdown` | Ephemeral resource page |
266272
| `docs/functions/<function name>.html.markdown` | Function page |
@@ -331,6 +337,20 @@ using the following data fields and functions:
331337
| `.HasVariadic` | bool | Does this function have a variadic argument? |
332338
| `.FunctionVariadicArgumentMarkdown` | string | a Markdown formatted Function variadic argument definition |
333339
340+
##### Action Fields
341+
342+
| Field | Type | Description |
343+
|-------------------------|--------|-------------------------------------------------------------------------------------------|
344+
| `.Name` | string | Name of the action (ex. `examplecloud_do_thing`) |
345+
| `.Type` | string | `Action` |
346+
| `.Description` | string | Action description |
347+
| `.HasExample` | bool | Is there an example file? |
348+
| `.ExampleFile` | string | Path to the file with the terraform configuration example |
349+
| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) |
350+
| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) |
351+
| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
352+
| `.SchemaMarkdown` | string | a Markdown formatted Action Schema definition |
353+
334354
#### Template Functions
335355
336356
| Function | Description |

‎cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ generating missing data source content
2727
data-source "scaffolding_example" fallback template exists, creating template
2828
generating missing function content
2929
generating missing ephemeral resource content
30+
generating missing action content
3031
generating missing provider content
3132
provider "terraform-provider-scaffolding" template exists, skipping
3233
rendering static website

‎cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ generating missing data source content
2727
data-source "scaffolding_example" template exists, skipping
2828
generating missing function content
2929
generating missing ephemeral resource content
30+
generating missing action content
3031
generating missing provider content
3132
provider "terraform-provider-scaffolding" template exists, skipping
3233
rendering static website

‎cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ generating missing data source content
2525
generating new template for data-source "scaffolding_example"
2626
generating missing function content
2727
generating missing ephemeral resource content
28+
generating missing action content
2829
generating missing provider content
2930
generating new template for "terraform-provider-scaffolding"
3031
rendering static website

‎cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ generating missing data source content
2424
data-source "null_data_source" fallback template exists, creating template
2525
generating missing function content
2626
generating missing ephemeral resource content
27+
generating missing action content
2728
generating missing provider content
2829
provider "terraform-provider-null" template exists, skipping
2930
rendering static website

‎cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ generating missing data source content
2020
generating missing function content
2121
generating new template for function "scaffolding"
2222
generating missing ephemeral resource content
23+
generating missing action content
2324
generating missing provider content
2425
generating new template for "terraform-provider-scaffolding"
2526
rendering static website

‎cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ cmpenv docs/data-sources/example.md expected-datasource.md
1111
cmpenv docs/resources/example.md expected-resource.md
1212
cmpenv docs/functions/example.md expected-function.md
1313
cmpenv docs/ephemeral-resources/example.md expected-ephemeral-resource.md
14+
cmpenv docs/actions/unlinked_example.md expected-unlinked-action.md
1415

1516

1617
-- expected-output.txt --
@@ -27,16 +28,70 @@ generating missing function content
2728
function "example" fallback template exists, creating template
2829
generating missing ephemeral resource content
2930
ephemeral resource "scaffolding_example" fallback template exists, creating template
31+
generating missing action content
32+
action "scaffolding_unlinked_example" fallback template exists, creating template
3033
generating missing provider content
3134
provider "terraform-provider-scaffolding" template exists, skipping
3235
rendering static website
3336
cleaning rendered website dir
3437
rendering templated website to static markdown
38+
rendering "actions/unlinked_example.md.tmpl"
3539
rendering "data-sources/example.md.tmpl"
3640
rendering "ephemeral-resources/example.md.tmpl"
3741
rendering "functions/example.md.tmpl"
3842
rendering "index.md.tmpl"
3943
rendering "resources/example.md.tmpl"
44+
-- expected-unlinked-action.md --
45+
# Data Fields
46+
47+
Name: scaffolding_unlinked_example
48+
Type: Action
49+
Description: Example unlinked action
50+
HasExample: true
51+
ExampleFile: $WORK/examples/actions/scaffolding_unlinked_example/action.tf
52+
ProviderName: terraform-provider-scaffolding
53+
ProviderShortName: scaffolding
54+
RenderedProviderName: terraform-provider-scaffolding
55+
SchemaMarkdown: <!-- action schema generated by tfplugindocs -->
56+
## Schema
57+
58+
### Required
59+
60+
- `required_attr` (String) Example required attribute
61+
62+
### Optional
63+
64+
- `optional_attr` (String) Example optional attribute
65+
66+
67+
68+
# Functions
69+
70+
lower: action
71+
plainmarkdown: Action
72+
prefixlines: Prefix: Action
73+
split: [scaffolding unlinked example]
74+
title: Action
75+
trimspace: Action
76+
upper: ACTION
77+
78+
# Conditionals and File Functions
79+
80+
printf tffile:
81+
## Example Usage
82+
83+
{{tffile "$WORK/examples/actions/scaffolding_unlinked_example/action.tf"}}
84+
85+
tffile:
86+
## Example Usage
87+
88+
```terraform
89+
action "scaffolding_unlinked_example" "example" {
90+
config {
91+
required_attr = "some-value"
92+
}
93+
}
94+
```
4095
-- expected-datasource.md --
4196
# Data Fields
4297

@@ -310,6 +365,44 @@ resource "scaffolding_example" "example" {
310365
configurable_attribute = "some-value"
311366
}
312367
```
368+
-- templates/actions.md.tmpl --
369+
# Data Fields
370+
371+
Name: {{.Name}}
372+
Type: {{.Type}}
373+
Description: {{.Description}}
374+
HasExample: {{.HasExample}}
375+
ExampleFile: {{.ExampleFile}}
376+
ProviderName: {{.ProviderName}}
377+
ProviderShortName: {{.ProviderShortName}}
378+
RenderedProviderName: {{.RenderedProviderName}}
379+
SchemaMarkdown: {{.SchemaMarkdown}}
380+
381+
# Functions
382+
383+
lower: {{ .Type | lower }}
384+
plainmarkdown: {{ .Type | plainmarkdown }}
385+
prefixlines: {{ .Type | prefixlines "Prefix: " }}
386+
split: {{ split .Name "_" }}
387+
title: {{ .Type | title }}
388+
trimspace: {{ .Type | trimspace }}
389+
upper: {{ .Type | upper }}
390+
391+
# Conditionals and File Functions
392+
393+
printf tffile:
394+
{{ if .HasExample -}}
395+
## Example Usage
396+
397+
{{ printf "{{tffile %q}}" .ExampleFile }}
398+
{{- end }}
399+
400+
tffile:
401+
{{ if .HasExample -}}
402+
## Example Usage
403+
404+
{{tffile .ExampleFile }}
405+
{{- end }}
313406
-- templates/data-sources.md.tmpl --
314407
# Data Fields
315408

@@ -572,6 +665,12 @@ The document generation tool looks for files in the following locations by defau
572665
* **provider/provider.tf** example file for the provider index page
573666
* **data-sources/`full data source name`/data-source.tf** example file for the named data source page
574667
* **resources/`full resource name`/resource.tf** example file for the named data source page
668+
-- examples/actions/scaffolding_unlinked_example/action.tf --
669+
action "scaffolding_unlinked_example" "example" {
670+
config {
671+
required_attr = "some-value"
672+
}
673+
}
575674
-- examples/data-sources/scaffolding_example/data-source.tf --
576675
data "scaffolding_example" "example" {
577676
configurable_attribute = "some-value"
@@ -623,6 +722,30 @@ resource "scaffolding_example" "example" {
623722
"description_kind": "markdown"
624723
}
625724
},
725+
"action_schemas": {
726+
"scaffolding_unlinked_example": {
727+
"version": 0,
728+
"block": {
729+
"attributes": {
730+
"required_attr": {
731+
"type": "string",
732+
"description": "Example required attribute",
733+
"description_kind": "plain",
734+
"required": true
735+
},
736+
"optional_attr": {
737+
"type": "string",
738+
"description": "Example optional attribute",
739+
"description_kind": "plain",
740+
"optional": true
741+
}
742+
},
743+
"description": "Example unlinked action",
744+
"description_kind": "plain"
745+
},
746+
"unlinked": {}
747+
}
748+
},
626749
"resource_schemas": {
627750
"scaffolding_example": {
628751
"version": 0,

0 commit comments

Comments
 (0)