diff --git a/.changes/unreleased/FEATURES-20241031-100833.yaml b/.changes/unreleased/FEATURES-20241031-100833.yaml new file mode 100644 index 00000000..0ef815b9 --- /dev/null +++ b/.changes/unreleased/FEATURES-20241031-100833.yaml @@ -0,0 +1,5 @@ +kind: FEATURES +body: 'generate: Add support for ephemeral resources' +time: 2024-10-31T10:08:33.606686-04:00 +custom: + Issue: "415" diff --git a/.changes/unreleased/FEATURES-20241031-100904.yaml b/.changes/unreleased/FEATURES-20241031-100904.yaml new file mode 100644 index 00000000..0d8a35e7 --- /dev/null +++ b/.changes/unreleased/FEATURES-20241031-100904.yaml @@ -0,0 +1,5 @@ +kind: FEATURES +body: 'migrate: Add support for ephemeral resources' +time: 2024-10-31T10:09:04.175251-04:00 +custom: + Issue: "415" diff --git a/.changes/unreleased/FEATURES-20241031-100919.yaml b/.changes/unreleased/FEATURES-20241031-100919.yaml new file mode 100644 index 00000000..6e2096ea --- /dev/null +++ b/.changes/unreleased/FEATURES-20241031-100919.yaml @@ -0,0 +1,5 @@ +kind: FEATURES +body: 'validate: Add support for ephemeral resources' +time: 2024-10-31T10:09:19.716278-04:00 +custom: + Issue: "415" diff --git a/README.md b/README.md index 6e30fd9e..dc1edecc 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,7 @@ When you run `tfplugindocs`, by default from the root directory of a provider co * Generate resource template files, if missing * Generate data source template files, if missing * Generate function template files, if missing (Requires Terraform v1.8.0+) +* Generate ephemeral resource template files, if missing (Requires Terraform v1.10.0+) * Copy all non-template files to the output website directory * Process all the remaining templates to generate files for the output website directory @@ -193,16 +194,18 @@ For templates: > **NOTE:** In the following conventional paths for templates, ``, ``, and `` do not include the provider prefix. -| Path | Description | -|-------------------------------------------------------|----------------------------------------| -| `templates/` | Root of templated docs | -| `templates/index.md[.tmpl]` | Docs index page (or template) | -| `templates/data-sources.md[.tmpl]` | Generic data source page (or template) | -| `templates/data-sources/.md[.tmpl]` | Data source page (or template) | -| `templates/functions.md[.tmpl]` | Generic function page (or template) | -| `templates/functions/.md[.tmpl]` | Function page (or template) | -| `templates/resources.md[.tmpl]` | Generic resource page (or template) | -| `templates/resources/.md[.tmpl]` | Resource page (or template) | +| Path | Description | +|--------------------------------------------------------------------|-----------------------------------------------| +| `templates/` | Root of templated docs | +| `templates/index.md[.tmpl]` | Docs index page (or template) | +| `templates/data-sources.md[.tmpl]` | Generic data source page (or template) | +| `templates/data-sources/.md[.tmpl]` | Data source page (or template) | +| `templates/ephemeral-resources.md[.tmpl]` | Generic ephemeral resource page (or template) | +| `templates/ephemeral-resources/.md[.tmpl]` | Ephemeral resource page (or template) | +| `templates/functions.md[.tmpl]` | Generic function page (or template) | +| `templates/functions/.md[.tmpl]` | Function page (or template) | +| `templates/resources.md[.tmpl]` | Generic resource page (or template) | +| `templates/resources/.md[.tmpl]` | Resource page (or template) | Note: the `.tmpl` extension is necessary, for the file to be correctly handled as a template. @@ -211,14 +214,15 @@ For examples: > **NOTE:** In the following conventional paths for examples, `` and `` include the provider prefix as well, but the provider prefix is **NOT** included in``. > For example, the data source [`caller_identity`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) in the `aws` provider would have an "example" conventional path of: `examples/data-sources/aws_caller_identity/data-source.tf` -| Path | Description | -|-----------------------------------------------------------|---------------------------------| -| `examples/` | Root of examples | -| `examples/provider/provider.tf` | Provider example config | -| `examples/data-sources//data-source.tf` | Data source example config | -| `examples/functions//function.tf` | Function example config | -| `examples/resources//resource.tf` | Resource example config | -| `examples/resources//import.sh` | Resource example import command | +| Path | Description | +|---------------------------------------------------------------------------|-----------------------------------| +| `examples/` | Root of examples | +| `examples/provider/provider.tf` | Provider example config | +| `examples/data-sources//data-source.tf` | Data source example config | +| `examples/ephemeral-resources//ephemeral-resource.tf` | Ephemeral resource example config | +| `examples/functions//function.tf` | Function example config | +| `examples/resources//resource.tf` | Resource example config | +| `examples/resources//import.sh` | Resource example import command | #### Migration @@ -229,25 +233,27 @@ The `migrate` subcommand assumes the following conventional paths for the render Legacy website directory structure: -| Path | Description | -|-------------------------------------------------------|-----------------------------| -| `website/` | Root of website docs | -| `website/docs/guides` | Root of guides subdirectory | -| `website/docs/index.html.markdown` | Docs index page | -| `website/docs/d/.html.markdown` | Data source page | -| `website/docs/functons/.html.markdown` | Functions page | -| `website/docs/r/.html.markdown` | Resource page | +| Path | Description | +|----------------------------------------------------------------------------|-----------------------------| +| `website/` | Root of website docs | +| `website/docs/guides` | Root of guides subdirectory | +| `website/docs/index.html.markdown` | Docs index page | +| `website/docs/d/.html.markdown` | Data source page | +| `website/docs/ephemeral-resources/.html.markdown` | Ephemeral resource page | +| `website/docs/functons/.html.markdown` | Functions page | +| `website/docs/r/.html.markdown` | Resource page | Docs website directory structure: -| Path | Description | -|------------------------------------------------------|-----------------------------| -| `docs/` | Root of website docs | -| `docs/guides` | Root of guides subdirectory | -| `docs/index.html.markdown` | Docs index page | -| `docs/data-sources/.html.markdown` | Data source page | -| `docs/functions/.html.markdown` | Function page | -| `docs/resources/.html.markdown` | Resource page | +| Path | Description | +|--------------------------------------------------------------------|-----------------------------| +| `docs/` | Root of website docs | +| `docs/guides` | Root of guides subdirectory | +| `docs/index.html.markdown` | Docs index page | +| `docs/data-sources/.html.markdown` | Data source page | +| `docs/ephemeral-resources/.html.markdown` | Ephemeral resource page | +| `docs/functions/.html.markdown` | Function page | +| `docs/resources/.html.markdown` | Resource page | Files named `index` (before the first `.`) in the website docs root directory and files in the `website/docs/d/`, `website/docs/r/`, `docs/data-sources/`, and `docs/resources/` subdirectories will be converted to `tfplugindocs` templates. @@ -275,7 +281,7 @@ using the following data fields and functions: | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` | | `.SchemaMarkdown` | string | a Markdown formatted Provider Schema definition | -##### Resources / Data Source Fields +##### Managed Resource / Ephemeral Resource / Data Source Fields | Field | Type | Description | |------------------------:|:------:|-------------------------------------------------------------------------------------------| diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar index 3f6010cd..cf5f7b6a 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar @@ -26,6 +26,7 @@ resource "scaffolding_example" fallback template exists, creating template generating missing data source content data-source "scaffolding_example" fallback template exists, creating template generating missing function content +generating missing ephemeral resource content generating missing provider content provider "terraform-provider-scaffolding" template exists, skipping rendering static website diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar index e4b3d497..a7354950 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar @@ -26,6 +26,7 @@ resource "scaffolding_example" template exists, skipping generating missing data source content data-source "scaffolding_example" template exists, skipping generating missing function content +generating missing ephemeral resource content generating missing provider content provider "terraform-provider-scaffolding" template exists, skipping rendering static website diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar index 01e3829e..bb6e91cc 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar @@ -24,6 +24,7 @@ generating new template for "scaffolding_example" generating missing data source content generating new template for data-source "scaffolding_example" generating missing function content +generating missing ephemeral resource content generating missing provider content generating new template for "terraform-provider-scaffolding" rendering static website diff --git a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar index 0c8fa4eb..263e85c4 100644 --- a/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar +++ b/cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar @@ -23,6 +23,7 @@ resource "null_resource" fallback template exists, creating template generating missing data source content data-source "null_data_source" fallback template exists, creating template generating missing function content +generating missing ephemeral resource content generating missing provider content provider "terraform-provider-null" template exists, skipping rendering static website diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar index 040d727b..b58019ee 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar @@ -19,6 +19,7 @@ generating new template for "scaffolding_example" generating missing data source content generating missing function content generating new template for function "scaffolding" +generating missing ephemeral resource content generating missing provider content generating new template for "terraform-provider-scaffolding" rendering static website diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar index 187ea8b9..3984d4e7 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar @@ -10,6 +10,7 @@ cmpenv docs/index.md expected-index.md cmpenv docs/data-sources/example.md expected-datasource.md cmpenv docs/resources/example.md expected-resource.md cmpenv docs/functions/example.md expected-function.md +cmpenv docs/ephemeral-resources/example.md expected-ephemeral-resource.md -- expected-output.txt -- @@ -24,12 +25,15 @@ generating missing data source content data-source "scaffolding_example" fallback template exists, creating template generating missing function content function "example" fallback template exists, creating template +generating missing ephemeral resource content +ephemeral resource "scaffolding_example" fallback template exists, creating template generating missing provider content provider "terraform-provider-scaffolding" template exists, skipping rendering static website cleaning rendered website dir rendering templated website to static markdown rendering "data-sources/example.md.tmpl" +rendering "ephemeral-resources/example.md.tmpl" rendering "functions/example.md.tmpl" rendering "index.md.tmpl" rendering "resources/example.md.tmpl" @@ -239,6 +243,63 @@ Import is supported using the following syntax: terraform import scaffolding_example.example ``` +tffile: +## Example Usage + +```terraform +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} +``` +-- expected-ephemeral-resource.md -- +# Data Fields + +Name: scaffolding_example +Type: Ephemeral Resource +Description: Example ephemeral resource +HasExample: true +ExampleFile: $WORK/examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf +HasImport: false +ProviderName: terraform-provider-scaffolding +ProviderShortName: scaffolding +RenderedProviderName: terraform-provider-scaffolding +SchemaMarkdown: +## Schema + +### Optional + +- `configurable_attribute` (String) Example configurable attribute +- `defaulted` (String) Example configurable attribute with default value + +### Read-Only + +- `id` (String) Example identifier + + + +# Functions + +lower: ephemeral resource +plainmarkdown: Ephemeral Resource +prefixlines: Prefix: Ephemeral Resource +split: [scaffolding example] +title: Ephemeral Resource +trimspace: Ephemeral Resource +upper: EPHEMERAL RESOURCE + +# Conditionals and File Functions + +printf codefile: + + +printf tffile: +## Example Usage + +{{tffile "$WORK/examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf"}} + +codefile: + + tffile: ## Example Usage @@ -438,6 +499,63 @@ tffile: {{ if .HasExample -}} ## Example Usage +{{tffile .ExampleFile }} +{{- end }} +-- templates/ephemeral-resources.md.tmpl -- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +Description: {{.Description}} +HasExample: {{.HasExample}} +ExampleFile: {{.ExampleFile}} +HasImport: {{.HasImport}} +ProviderName: {{.ProviderName}} +ProviderShortName: {{.ProviderShortName}} +RenderedProviderName: {{.RenderedProviderName}} +SchemaMarkdown: {{.SchemaMarkdown}} + +# Functions + +lower: {{ .Type | lower }} +plainmarkdown: {{ .Type | plainmarkdown }} +prefixlines: {{ .Type | prefixlines "Prefix: " }} +split: {{ split .Name "_" }} +title: {{ .Type | title }} +trimspace: {{ .Type | trimspace }} +upper: {{ .Type | upper }} + +# Conditionals and File Functions + +printf codefile: +{{ if .HasImport -}} +## Import + +Import is supported using the following syntax: + +{{ printf "{{codefile \"shell\" %q}}" .ImportFile }} +{{- end }} + +printf tffile: +{{ if .HasExample -}} +## Example Usage + +{{ printf "{{tffile %q}}" .ExampleFile }} +{{- end }} + +codefile: +{{ if .HasImport -}} +## Import + +Import is supported using the following syntax: + +{{codefile "shell" .ImportFile }} +{{- end }} + +tffile: +{{ if .HasExample -}} +## Example Usage + {{tffile .ExampleFile }} {{- end }} -- examples/README.md -- @@ -468,98 +586,132 @@ resource "scaffolding_example" "example" { } -- examples/resources/scaffolding_example/import.sh -- terraform import scaffolding_example.example +-- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf -- +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} -- schema.json -- { - "format_version": "1.0", - "provider_schemas": { - "registry.terraform.io/hashicorp/scaffolding": { - "provider": { - "version": 0, - "block": { - "attributes": { - "endpoint": { - "type": "string", - "description": "Example provider attribute", - "description_kind": "markdown", - "optional": true - } - }, - "description": "Example provider", - "description_kind": "markdown" - } - }, - "resource_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "defaulted": { - "type": "string", - "description": "Example configurable attribute with default value", - "description_kind": "markdown", - "optional": true, - "computed": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "format_version": "1.0", + "provider_schemas": { + "registry.terraform.io/hashicorp/scaffolding": { + "provider": { + "version": 0, + "block": { + "attributes": { + "endpoint": { + "type": "string", + "description": "Example provider attribute", + "description_kind": "markdown", + "optional": true + } + }, + "description": "Example provider", + "description_kind": "markdown" + } }, - "description": "Example resource", - "description_kind": "markdown" - } - } - }, - "data_source_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example resource", + "description_kind": "markdown" + } + } }, - "description": "Example data source", - "description_kind": "markdown" - } - } - }, - "functions": { - "example": { - "description": "Given a string value, returns the same value.", - "summary": "Echo a string", - "return_type": "string", - "parameters": [ - { - "name": "input", - "description": "Value to echo.", - "type": "string" + "ephemeral_resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example ephemeral resource", + "description_kind": "markdown" + } + } + }, + "data_source_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example data source", + "description_kind": "markdown" + } + } + }, + "functions": { + "example": { + "description": "Given a string value, returns the same value.", + "summary": "Echo a string", + "return_type": "string", + "parameters": [ + { + "name": "input", + "description": "Value to echo.", + "type": "string" + } + ], + "variadic_parameter": { + "name": "variadicInput", + "description": "Variadic input to echo.", + "type": "string" + } + } } - ], - "variadic_parameter": { - "name": "variadicInput", - "description": "Variadic input to echo.", - "type": "string" - } } - } } - } } \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_legacy_docs.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_legacy_docs.txtar index 03973af1..9d175252 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_legacy_docs.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_legacy_docs.txtar @@ -22,6 +22,11 @@ cmp templates/functions/example.markdown docs/functions/example.markdown cmp templates/functions/example.html.markdown docs/functions/example.html.markdown cmp templates/functions/example.html.md docs/functions/example.html.md +cmp templates/ephemeral-resources/example.md docs/ephemeral-resources/example.md +cmp templates/ephemeral-resources/example.markdown docs/ephemeral-resources/example.markdown +cmp templates/ephemeral-resources/example.html.markdown docs/ephemeral-resources/example.html.markdown +cmp templates/ephemeral-resources/example.html.md docs/ephemeral-resources/example.html.md + cmp templates/index.md docs/index.md cmp templates/index.markdown docs/index.markdown cmp templates/index.html.markdown docs/index.html.markdown @@ -38,6 +43,8 @@ generating missing data source content data-source "scaffolding_example" static file exists, skipping generating missing function content function "example" static file exists, skipping +generating missing ephemeral resource content +ephemeral resource "scaffolding_example" static file exists, skipping generating missing provider content provider "terraform-provider-scaffolding" static file exists, skipping rendering static website @@ -47,6 +54,10 @@ copying non-template file: "d/example.html.markdown" copying non-template file: "d/example.html.md" copying non-template file: "d/example.markdown" copying non-template file: "d/example.md" +copying non-template file: "ephemeral-resources/example.html.markdown" +copying non-template file: "ephemeral-resources/example.html.md" +copying non-template file: "ephemeral-resources/example.markdown" +copying non-template file: "ephemeral-resources/example.md" copying non-template file: "functions/example.html.markdown" copying non-template file: "functions/example.html.md" copying non-template file: "functions/example.markdown" @@ -117,6 +128,26 @@ Type: {{.Type}} -- templates/functions/example.html.md -- # Data Fields +Name: {{.Name}} +Type: {{.Type}} +-- templates/ephemeral-resources/example.md -- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +-- templates/ephemeral-resources/example.markdown -- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +-- templates/ephemeral-resources/example.html.markdown -- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +-- templates/ephemeral-resources/example.html.md -- +# Data Fields + Name: {{.Name}} Type: {{.Type}} -- templates/index.md -- @@ -161,100 +192,134 @@ provider "scaffolding" { resource "scaffolding_example" "example" { configurable_attribute = "some-value" } +-- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf -- +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} -- examples/resources/scaffolding_example/import.sh -- terraform import scaffolding_example.example -- schema.json -- { - "format_version": "1.0", - "provider_schemas": { - "registry.terraform.io/hashicorp/scaffolding": { - "provider": { - "version": 0, - "block": { - "attributes": { - "endpoint": { - "type": "string", - "description": "Example provider attribute", - "description_kind": "markdown", - "optional": true - } - }, - "description": "Example provider", - "description_kind": "markdown" - } - }, - "resource_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "defaulted": { - "type": "string", - "description": "Example configurable attribute with default value", - "description_kind": "markdown", - "optional": true, - "computed": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "format_version": "1.0", + "provider_schemas": { + "registry.terraform.io/hashicorp/scaffolding": { + "provider": { + "version": 0, + "block": { + "attributes": { + "endpoint": { + "type": "string", + "description": "Example provider attribute", + "description_kind": "markdown", + "optional": true + } + }, + "description": "Example provider", + "description_kind": "markdown" + } }, - "description": "Example resource", - "description_kind": "markdown" - } - } - }, - "data_source_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example resource", + "description_kind": "markdown" + } + } }, - "description": "Example data source", - "description_kind": "markdown" - } - } - }, - "functions": { - "example": { - "description": "Given a string value, returns the same value.", - "summary": "Echo a string", - "return_type": "string", - "parameters": [ - { - "name": "input", - "description": "Value to echo.", - "type": "string" + "ephemeral_resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example ephemeral resource", + "description_kind": "markdown" + } + } + }, + "data_source_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example data source", + "description_kind": "markdown" + } + } + }, + "functions": { + "example": { + "description": "Given a string value, returns the same value.", + "summary": "Echo a string", + "return_type": "string", + "parameters": [ + { + "name": "input", + "description": "Value to echo.", + "type": "string" + } + ], + "variadic_parameter": { + "name": "variadicInput", + "description": "Variadic input to echo.", + "type": "string" + } + } } - ], - "variadic_parameter": { - "name": "variadicInput", - "description": "Variadic input to echo.", - "type": "string" - } } - } } - } } \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar index 15680887..50d254eb 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_named_templates.txtar @@ -10,6 +10,7 @@ cmpenv docs/index.md expected-index.md cmpenv docs/data-sources/example.md expected-datasource.md cmpenv docs/resources/example.md expected-resource.md cmpenv docs/functions/example.md expected-function.md +cmpenv docs/ephemeral-resources/example.md expected-ephemeral-resource.md -- expected-output.txt -- rendering website for provider "terraform-provider-scaffolding" (as "terraform-provider-scaffolding") @@ -23,12 +24,15 @@ generating missing data source content data-source "scaffolding_example" template exists, skipping generating missing function content function "example" template exists, skipping +generating missing ephemeral resource content +ephemeral resource "scaffolding_example" template exists, skipping generating missing provider content provider "terraform-provider-scaffolding" template exists, skipping rendering static website cleaning rendered website dir rendering templated website to static markdown rendering "data-sources/example.md.tmpl" +rendering "ephemeral-resources/example.md.tmpl" rendering "functions/example.md.tmpl" rendering "index.md.tmpl" rendering "resources/example.md.tmpl" @@ -238,6 +242,63 @@ Import is supported using the following syntax: terraform import scaffolding_example.example ``` +tffile: +## Example Usage + +```terraform +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} +``` +-- expected-ephemeral-resource.md -- +# Data Fields + +Name: scaffolding_example +Type: Ephemeral Resource +Description: Example ephemeral resource +HasExample: true +ExampleFile: $WORK/examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf +HasImport: false +ProviderName: terraform-provider-scaffolding +ProviderShortName: scaffolding +RenderedProviderName: terraform-provider-scaffolding +SchemaMarkdown: +## Schema + +### Optional + +- `configurable_attribute` (String) Example configurable attribute +- `defaulted` (String) Example configurable attribute with default value + +### Read-Only + +- `id` (String) Example identifier + + + +# Functions + +lower: ephemeral resource +plainmarkdown: Ephemeral Resource +prefixlines: Prefix: Ephemeral Resource +split: [scaffolding example] +title: Ephemeral Resource +trimspace: Ephemeral Resource +upper: EPHEMERAL RESOURCE + +# Conditionals and File Functions + +printf codefile: + + +printf tffile: +## Example Usage + +{{tffile "$WORK/examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf"}} + +codefile: + + tffile: ## Example Usage @@ -437,6 +498,63 @@ tffile: {{ if .HasExample -}} ## Example Usage +{{tffile .ExampleFile }} +{{- end }} +-- templates/ephemeral-resources/example.md.tmpl -- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +Description: {{.Description}} +HasExample: {{.HasExample}} +ExampleFile: {{.ExampleFile}} +HasImport: {{.HasImport}} +ProviderName: {{.ProviderName}} +ProviderShortName: {{.ProviderShortName}} +RenderedProviderName: {{.RenderedProviderName}} +SchemaMarkdown: {{.SchemaMarkdown}} + +# Functions + +lower: {{ .Type | lower }} +plainmarkdown: {{ .Type | plainmarkdown }} +prefixlines: {{ .Type | prefixlines "Prefix: " }} +split: {{ split .Name "_" }} +title: {{ .Type | title }} +trimspace: {{ .Type | trimspace }} +upper: {{ .Type | upper }} + +# Conditionals and File Functions + +printf codefile: +{{ if .HasImport -}} +## Import + +Import is supported using the following syntax: + +{{ printf "{{codefile \"shell\" %q}}" .ImportFile }} +{{- end }} + +printf tffile: +{{ if .HasExample -}} +## Example Usage + +{{ printf "{{tffile %q}}" .ExampleFile }} +{{- end }} + +codefile: +{{ if .HasImport -}} +## Import + +Import is supported using the following syntax: + +{{codefile "shell" .ImportFile }} +{{- end }} + +tffile: +{{ if .HasExample -}} +## Example Usage + {{tffile .ExampleFile }} {{- end }} -- examples/README.md -- @@ -465,100 +583,134 @@ provider "scaffolding" { resource "scaffolding_example" "example" { configurable_attribute = "some-value" } +-- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf -- +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} -- examples/resources/scaffolding_example/import.sh -- terraform import scaffolding_example.example -- schema.json -- { - "format_version": "1.0", - "provider_schemas": { - "registry.terraform.io/hashicorp/scaffolding": { - "provider": { - "version": 0, - "block": { - "attributes": { - "endpoint": { - "type": "string", - "description": "Example provider attribute", - "description_kind": "markdown", - "optional": true - } - }, - "description": "Example provider", - "description_kind": "markdown" - } - }, - "resource_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "defaulted": { - "type": "string", - "description": "Example configurable attribute with default value", - "description_kind": "markdown", - "optional": true, - "computed": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "format_version": "1.0", + "provider_schemas": { + "registry.terraform.io/hashicorp/scaffolding": { + "provider": { + "version": 0, + "block": { + "attributes": { + "endpoint": { + "type": "string", + "description": "Example provider attribute", + "description_kind": "markdown", + "optional": true + } + }, + "description": "Example provider", + "description_kind": "markdown" + } }, - "description": "Example resource", - "description_kind": "markdown" - } - } - }, - "data_source_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example resource", + "description_kind": "markdown" + } + } }, - "description": "Example data source", - "description_kind": "markdown" - } - } - }, - "functions": { - "example": { - "description": "Given a string value, returns the same value.", - "summary": "Echo a string", - "return_type": "string", - "parameters": [ - { - "name": "input", - "description": "Value to echo.", - "type": "string" + "ephemeral_resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example ephemeral resource", + "description_kind": "markdown" + } + } + }, + "data_source_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example data source", + "description_kind": "markdown" + } + } + }, + "functions": { + "example": { + "description": "Given a string value, returns the same value.", + "summary": "Echo a string", + "return_type": "string", + "parameters": [ + { + "name": "input", + "description": "Value to echo.", + "type": "string" + } + ], + "variadic_parameter": { + "name": "variadicInput", + "description": "Variadic input to echo.", + "type": "string" + } + } } - ], - "variadic_parameter": { - "name": "variadicInput", - "description": "Variadic input to echo.", - "type": "string" - } } - } } - } } \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar index 8ac9b9ad..861b396e 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_no_templates.txtar @@ -9,6 +9,7 @@ cmp docs/index.md expected-index.md cmp docs/data-sources/example.md expected-datasource.md cmp docs/resources/example.md expected-resource.md cmp docs/functions/example.md expected-function.md +cmp docs/ephemeral-resources/example.md expected-ephemeral-resource.md -- expected-output.txt -- rendering website for provider "terraform-provider-scaffolding" (as "terraform-provider-scaffolding") @@ -21,12 +22,15 @@ generating missing data source content generating new template for data-source "scaffolding_example" generating missing function content generating new template for function "example" +generating missing ephemeral resource content +generating new template for "scaffolding_example" generating missing provider content generating new template for "terraform-provider-scaffolding" rendering static website cleaning rendered website dir rendering templated website to static markdown rendering "data-sources/example.md.tmpl" +rendering "ephemeral-resources/example.md.tmpl" rendering "functions/example.md.tmpl" rendering "index.md.tmpl" rendering "resources/example.md.tmpl" @@ -153,6 +157,38 @@ resource "scaffolding_example" "example" { ### Read-Only +- `id` (String) Example identifier +-- expected-ephemeral-resource.md -- +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "scaffolding_example Ephemeral Resource - terraform-provider-scaffolding" +subcategory: "" +description: |- + Example ephemeral resource +--- + +# scaffolding_example (Ephemeral Resource) + +Example ephemeral resource + +## Example Usage + +```terraform +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} +``` + + +## Schema + +### Optional + +- `configurable_attribute` (String) Example configurable attribute +- `defaulted` (String) Example configurable attribute with default value + +### Read-Only + - `id` (String) Example identifier -- examples/README.md -- # Examples @@ -180,99 +216,133 @@ provider "scaffolding" { resource "scaffolding_example" "example" { configurable_attribute = "some-value" } +-- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf -- +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} -- schema.json -- { - "format_version": "1.0", - "provider_schemas": { - "registry.terraform.io/hashicorp/scaffolding": { - "provider": { - "version": 0, - "block": { - "attributes": { - "endpoint": { - "type": "string", - "description": "Example provider attribute", - "description_kind": "markdown", - "optional": true - } - }, - "description": "Example provider", - "description_kind": "markdown" - } - }, - "resource_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "defaulted": { - "type": "string", - "description": "Example configurable attribute with default value", - "description_kind": "markdown", - "optional": true, - "computed": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "format_version": "1.0", + "provider_schemas": { + "registry.terraform.io/hashicorp/scaffolding": { + "provider": { + "version": 0, + "block": { + "attributes": { + "endpoint": { + "type": "string", + "description": "Example provider attribute", + "description_kind": "markdown", + "optional": true + } + }, + "description": "Example provider", + "description_kind": "markdown" + } }, - "description": "Example resource", - "description_kind": "markdown" - } - } - }, - "data_source_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example resource", + "description_kind": "markdown" + } + } }, - "description": "Example data source", - "description_kind": "markdown" - } - } - }, - "functions": { - "example": { - "description": "Given a string value, returns the same value.", - "summary": "Echo a string", - "return_type": "string", - "parameters": [ - { - "name": "input", - "description": "Value to echo.", - "type": "string" + "ephemeral_resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example ephemeral resource", + "description_kind": "markdown" + } + } + }, + "data_source_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example data source", + "description_kind": "markdown" + } + } + }, + "functions": { + "example": { + "description": "Given a string value, returns the same value.", + "summary": "Echo a string", + "return_type": "string", + "parameters": [ + { + "name": "input", + "description": "Value to echo.", + "type": "string" + } + ], + "variadic_parameter": { + "name": "variadicInput", + "description": "Variadic input to echo.", + "type": "string" + } + } } - ], - "variadic_parameter": { - "name": "variadicInput", - "description": "Variadic input to echo.", - "type": "string" - } } - } } - } } \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_static_files.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_static_files.txtar index bc0309b3..f37cdfc4 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_static_files.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_static_files.txtar @@ -22,6 +22,11 @@ cmp templates/functions/example.markdown docs/functions/example.markdown cmp templates/functions/example.html.markdown docs/functions/example.html.markdown cmp templates/functions/example.html.md docs/functions/example.html.md +cmp templates/ephemeral-resources/example.md docs/ephemeral-resources/example.md +cmp templates/ephemeral-resources/example.markdown docs/ephemeral-resources/example.markdown +cmp templates/ephemeral-resources/example.html.markdown docs/ephemeral-resources/example.html.markdown +cmp templates/ephemeral-resources/example.html.md docs/ephemeral-resources/example.html.md + cmp templates/index.md docs/index.md cmp templates/index.markdown docs/index.markdown cmp templates/index.html.markdown docs/index.html.markdown @@ -38,6 +43,8 @@ generating missing data source content data-source "scaffolding_example" static file exists, skipping generating missing function content function "example" static file exists, skipping +generating missing ephemeral resource content +ephemeral resource "scaffolding_example" static file exists, skipping generating missing provider content provider "terraform-provider-scaffolding" static file exists, skipping rendering static website @@ -47,6 +54,10 @@ copying non-template file: "data-sources/example.html.markdown" copying non-template file: "data-sources/example.html.md" copying non-template file: "data-sources/example.markdown" copying non-template file: "data-sources/example.md" +copying non-template file: "ephemeral-resources/example.html.markdown" +copying non-template file: "ephemeral-resources/example.html.md" +copying non-template file: "ephemeral-resources/example.markdown" +copying non-template file: "ephemeral-resources/example.md" copying non-template file: "functions/example.html.markdown" copying non-template file: "functions/example.html.md" copying non-template file: "functions/example.markdown" @@ -117,6 +128,26 @@ Type: {{.Type}} -- templates/functions/example.html.md -- # Data Fields +Name: {{.Name}} +Type: {{.Type}} +-- templates/ephemeral-resources/example.md -- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +-- templates/ephemeral-resources/example.markdown -- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +-- templates/ephemeral-resources/example.html.markdown -- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +-- templates/ephemeral-resources/example.html.md -- +# Data Fields + Name: {{.Name}} Type: {{.Type}} -- templates/index.md -- @@ -161,100 +192,134 @@ provider "scaffolding" { resource "scaffolding_example" "example" { configurable_attribute = "some-value" } +-- examples/ephemeral-resources/scaffolding_example/ephemeral-resource.tf -- +resource "scaffolding_example" "example" { + configurable_attribute = "some-value" +} -- examples/resources/scaffolding_example/import.sh -- terraform import scaffolding_example.example -- schema.json -- { - "format_version": "1.0", - "provider_schemas": { - "registry.terraform.io/hashicorp/scaffolding": { - "provider": { - "version": 0, - "block": { - "attributes": { - "endpoint": { - "type": "string", - "description": "Example provider attribute", - "description_kind": "markdown", - "optional": true - } - }, - "description": "Example provider", - "description_kind": "markdown" - } - }, - "resource_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "defaulted": { - "type": "string", - "description": "Example configurable attribute with default value", - "description_kind": "markdown", - "optional": true, - "computed": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "format_version": "1.0", + "provider_schemas": { + "registry.terraform.io/hashicorp/scaffolding": { + "provider": { + "version": 0, + "block": { + "attributes": { + "endpoint": { + "type": "string", + "description": "Example provider attribute", + "description_kind": "markdown", + "optional": true + } + }, + "description": "Example provider", + "description_kind": "markdown" + } }, - "description": "Example resource", - "description_kind": "markdown" - } - } - }, - "data_source_schemas": { - "scaffolding_example": { - "version": 0, - "block": { - "attributes": { - "configurable_attribute": { - "type": "string", - "description": "Example configurable attribute", - "description_kind": "markdown", - "optional": true - }, - "id": { - "type": "string", - "description": "Example identifier", - "description_kind": "markdown", - "computed": true - } + "resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example resource", + "description_kind": "markdown" + } + } }, - "description": "Example data source", - "description_kind": "markdown" - } - } - }, - "functions": { - "example": { - "description": "Given a string value, returns the same value.", - "summary": "Echo a string", - "return_type": "string", - "parameters": [ - { - "name": "input", - "description": "Value to echo.", - "type": "string" + "ephemeral_resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example ephemeral resource", + "description_kind": "markdown" + } + } + }, + "data_source_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example data source", + "description_kind": "markdown" + } + } + }, + "functions": { + "example": { + "description": "Given a string value, returns the same value.", + "summary": "Echo a string", + "return_type": "string", + "parameters": [ + { + "name": "input", + "description": "Value to echo.", + "type": "string" + } + ], + "variadic_parameter": { + "name": "variadicInput", + "description": "Variadic input to echo.", + "type": "string" + } + } } - ], - "variadic_parameter": { - "name": "variadicInput", - "description": "Variadic input to echo.", - "type": "string" - } } - } } - } } \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar index 943c54c8..21628fae 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/nested_id_attribute.txtar @@ -17,6 +17,7 @@ generating missing resource content generating new template for "scaffolding_example" generating missing data source content generating missing function content +generating missing ephemeral resource content generating missing provider content generating new template for "terraform-provider-scaffolding" rendering static website diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar index 91597c24..e05ef443 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/generate/null_provider_success.txtar @@ -18,6 +18,7 @@ resource "null_resource" fallback template exists, creating template generating missing data source content data-source "null_data_source" fallback template exists, creating template generating missing function content +generating missing ephemeral resource content generating missing provider content provider "terraform-provider-null" template exists, skipping rendering static website diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_idempotency.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_idempotency.txtar index f2d0dcb6..7427ef84 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_idempotency.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_idempotency.txtar @@ -17,6 +17,7 @@ cmpenv templates/resources/offset.md.tmpl exp-templates/resources/offset.md.tmpl cmpenv templates/resources/rotating.md.tmpl exp-templates/resources/rotating.md.tmpl cmpenv templates/resources/sleep.md.tmpl exp-templates/resources/sleep.md.tmpl cmpenv templates/resources/static.md.tmpl exp-templates/resources/static.md.tmpl +cmpenv templates/ephemeral-resources/ephemeral_static.md.tmpl exp-templates/ephemeral-resources/ephemeral_static.md.tmpl # Check generated example files cmpenv examples/example_1.tf examples/example_1.tf @@ -37,13 +38,25 @@ cmpenv examples/resources/sleep/example_3.tf exp-examples/resources/sleep/exampl cmpenv examples/resources/sleep/import_1.sh exp-examples/resources/sleep/import_1.sh cmpenv examples/resources/sleep/import_2.sh exp-examples/resources/sleep/import_2.sh -cmpenv examples/resources/static/example_1.tf examples/resources/static/example_1.tf -cmpenv examples/resources/static/example_2.tf examples/resources/static/example_2.tf -cmpenv examples/resources/static/import_1.sh examples/resources/static/import_1.sh +cmpenv examples/resources/static/example_1.tf exp-examples/resources/static/example_1.tf +cmpenv examples/resources/static/example_2.tf exp-examples/resources/static/example_2.tf +cmpenv examples/resources/static/import_1.sh exp-examples/resources/static/import_1.sh + +cmpenv examples/ephemeral-resources/ephemeral_static/example_1.tf exp-examples/ephemeral-resources/ephemeral_static/example_1.tf +cmpenv examples/ephemeral-resources/ephemeral_static/example_2.tf exp-examples/ephemeral-resources/ephemeral_static/example_2.tf +cmpenv examples/ephemeral-resources/ephemeral_static/import_1.sh exp-examples/ephemeral-resources/ephemeral_static/import_1.sh -- expected-output.txt -- migrating website from "$WORK/docs" to "$WORK/templates" -migrating functons directory: functions +migrating ephemeral resources directory: ephemeral-resources +migrating file "ephemeral_static.html.markdown" +extracting YAML frontmatter to "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +extracting code examples from "ephemeral_static.html.markdown" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_1.tf" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_2.tf" +creating import file "$WORK/examples/ephemeral-resources/ephemeral_static/import_1.sh" +finished creating template "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +migrating functions directory: functions migrating file "rfc3339_parse.html.markdown" extracting YAML frontmatter to "$WORK/templates/functions/rfc3339_parse.md.tmpl" extracting code examples from "rfc3339_parse.html.markdown" @@ -516,6 +529,85 @@ This resource can be imported using the UTC RFC3339 value, e.g. $ terraform import time_static.example 2020-02-12T06:36:13Z ``` +The `triggers` argument cannot be imported. +-- docs/ephemeral-resources/ephemeral_static.html.markdown -- +--- +layout: "time" +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +```hcl +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +``` + +### Triggers Usage + +```hcl +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +``` + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +```console +$ terraform import time_static.example 2020-02-12T06:36:13Z +``` + The `triggers` argument cannot be imported. -- exp-examples/example_1.tf -- resource "time_static" "ami_update" { @@ -663,6 +755,33 @@ resource "aws_instance" "server" { } -- exp-examples/resources/static/import_1.sh -- $ terraform import time_static.example 2020-02-12T06:36:13Z +-- exp-examples/ephemeral-resources/ephemeral_static/example_1.tf -- +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +-- exp-examples/ephemeral-resources/ephemeral_static/example_2.tf -- +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +-- exp-examples/ephemeral-resources/ephemeral_static/import_1.sh -- +$ terraform import time_static.example 2020-02-12T06:36:13Z -- exp-templates/index.md.tmpl -- --- page_title: "Provider: Time" @@ -963,4 +1082,59 @@ This resource can be imported using the UTC RFC3339 value, e.g. {{codefile "shell" "examples/resources/static/import_1.sh"}} +The `triggers` argument cannot be imported. +-- exp-templates/ephemeral-resources/ephemeral_static.md.tmpl -- +--- +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates. + +For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}} + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_1.tf"}} + +### Triggers Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_2.tf"}} + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +{{codefile "shell" "examples/ephemeral-resources/ephemeral_static/import_1.sh"}} + The `triggers` argument cannot be imported. \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_docs_website.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_docs_website.txtar index ea93de7c..6928f37a 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_docs_website.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_docs_website.txtar @@ -15,6 +15,7 @@ cmpenv templates/resources/offset.md.tmpl exp-templates/resources/offset.md.tmpl cmpenv templates/resources/rotating.md.tmpl exp-templates/resources/rotating.md.tmpl cmpenv templates/resources/sleep.md.tmpl exp-templates/resources/sleep.md.tmpl cmpenv templates/resources/static.md.tmpl exp-templates/resources/static.md.tmpl +cmpenv templates/ephemeral-resources/ephemeral_static.md.tmpl exp-templates/ephemeral-resources/ephemeral_static.md.tmpl # Check generated example files cmpenv examples/example_1.tf examples/example_1.tf @@ -35,13 +36,25 @@ cmpenv examples/resources/sleep/example_3.tf exp-examples/resources/sleep/exampl cmpenv examples/resources/sleep/import_1.sh exp-examples/resources/sleep/import_1.sh cmpenv examples/resources/sleep/import_2.sh exp-examples/resources/sleep/import_2.sh -cmpenv examples/resources/static/example_1.tf examples/resources/static/example_1.tf -cmpenv examples/resources/static/example_2.tf examples/resources/static/example_2.tf -cmpenv examples/resources/static/import_1.sh examples/resources/static/import_1.sh +cmpenv examples/resources/static/example_1.tf exp-examples/resources/static/example_1.tf +cmpenv examples/resources/static/example_2.tf exp-examples/resources/static/example_2.tf +cmpenv examples/resources/static/import_1.sh exp-examples/resources/static/import_1.sh + +cmpenv examples/ephemeral-resources/ephemeral_static/example_1.tf exp-examples/ephemeral-resources/ephemeral_static/example_1.tf +cmpenv examples/ephemeral-resources/ephemeral_static/example_2.tf exp-examples/ephemeral-resources/ephemeral_static/example_2.tf +cmpenv examples/ephemeral-resources/ephemeral_static/import_1.sh exp-examples/ephemeral-resources/ephemeral_static/import_1.sh -- expected-output.txt -- migrating website from "$WORK/docs" to "$WORK/templates" -migrating functons directory: functions +migrating ephemeral resources directory: ephemeral-resources +migrating file "ephemeral_static.html.markdown" +extracting YAML frontmatter to "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +extracting code examples from "ephemeral_static.html.markdown" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_1.tf" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_2.tf" +creating import file "$WORK/examples/ephemeral-resources/ephemeral_static/import_1.sh" +finished creating template "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +migrating functions directory: functions migrating file "rfc3339_parse.html.markdown" extracting YAML frontmatter to "$WORK/templates/functions/rfc3339_parse.md.tmpl" extracting code examples from "rfc3339_parse.html.markdown" @@ -514,6 +527,85 @@ This resource can be imported using the UTC RFC3339 value, e.g. $ terraform import time_static.example 2020-02-12T06:36:13Z ``` +The `triggers` argument cannot be imported. +-- docs/ephemeral-resources/ephemeral_static.html.markdown -- +--- +layout: "time" +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +```hcl +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +``` + +### Triggers Usage + +```hcl +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +``` + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +```console +$ terraform import time_static.example 2020-02-12T06:36:13Z +``` + The `triggers` argument cannot be imported. -- exp-examples/example_1.tf -- resource "time_static" "ami_update" { @@ -661,6 +753,33 @@ resource "aws_instance" "server" { } -- exp-examples/resources/static/import_1.sh -- $ terraform import time_static.example 2020-02-12T06:36:13Z +-- exp-examples/ephemeral-resources/ephemeral_static/example_1.tf -- +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +-- exp-examples/ephemeral-resources/ephemeral_static/example_2.tf -- +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +-- exp-examples/ephemeral-resources/ephemeral_static/import_1.sh -- +$ terraform import time_static.example 2020-02-12T06:36:13Z -- exp-templates/index.md.tmpl -- --- page_title: "Provider: Time" @@ -961,4 +1080,59 @@ This resource can be imported using the UTC RFC3339 value, e.g. {{codefile "shell" "examples/resources/static/import_1.sh"}} +The `triggers` argument cannot be imported. +-- exp-templates/ephemeral-resources/ephemeral_static.md.tmpl -- +--- +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates. + +For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}} + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_1.tf"}} + +### Triggers Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_2.tf"}} + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +{{codefile "shell" "examples/ephemeral-resources/ephemeral_static/import_1.sh"}} + The `triggers` argument cannot be imported. \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_docs_website_with_prefix.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_docs_website_with_prefix.txtar index 0192624b..11704c44 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_docs_website_with_prefix.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_docs_website_with_prefix.txtar @@ -15,6 +15,7 @@ cmpenv templates/resources/offset.md.tmpl exp-templates/resources/offset.md.tmpl cmpenv templates/resources/rotating.md.tmpl exp-templates/resources/rotating.md.tmpl cmpenv templates/resources/sleep.md.tmpl exp-templates/resources/sleep.md.tmpl cmpenv templates/resources/static.md.tmpl exp-templates/resources/static.md.tmpl +cmpenv templates/ephemeral-resources/ephemeral_static.md.tmpl exp-templates/ephemeral-resources/ephemeral_static.md.tmpl # Check generated example files cmpenv examples/example_1.tf examples/example_1.tf @@ -35,13 +36,25 @@ cmpenv examples/resources/sleep/example_3.tf exp-examples/resources/sleep/exampl cmpenv examples/resources/sleep/import_1.sh exp-examples/resources/sleep/import_1.sh cmpenv examples/resources/sleep/import_2.sh exp-examples/resources/sleep/import_2.sh -cmpenv examples/resources/static/example_1.tf examples/resources/static/example_1.tf -cmpenv examples/resources/static/example_2.tf examples/resources/static/example_2.tf -cmpenv examples/resources/static/import_1.sh examples/resources/static/import_1.sh +cmpenv examples/resources/static/example_1.tf exp-examples/resources/static/example_1.tf +cmpenv examples/resources/static/example_2.tf exp-examples/resources/static/example_2.tf +cmpenv examples/resources/static/import_1.sh exp-examples/resources/static/import_1.sh + +cmpenv examples/ephemeral-resources/ephemeral_static/example_1.tf exp-examples/ephemeral-resources/ephemeral_static/example_1.tf +cmpenv examples/ephemeral-resources/ephemeral_static/example_2.tf exp-examples/ephemeral-resources/ephemeral_static/example_2.tf +cmpenv examples/ephemeral-resources/ephemeral_static/import_1.sh exp-examples/ephemeral-resources/ephemeral_static/import_1.sh -- expected-output.txt -- migrating website from "$WORK/docs" to "$WORK/templates" -migrating functons directory: functions +migrating ephemeral resources directory: ephemeral-resources +migrating file "time_ephemeral_static.html.markdown" +extracting YAML frontmatter to "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +extracting code examples from "time_ephemeral_static.html.markdown" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_1.tf" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_2.tf" +creating import file "$WORK/examples/ephemeral-resources/ephemeral_static/import_1.sh" +finished creating template "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +migrating functions directory: functions migrating file "time_rfc3339_parse.html.markdown" extracting YAML frontmatter to "$WORK/templates/functions/rfc3339_parse.md.tmpl" extracting code examples from "time_rfc3339_parse.html.markdown" @@ -514,6 +527,85 @@ This resource can be imported using the UTC RFC3339 value, e.g. $ terraform import time_static.example 2020-02-12T06:36:13Z ``` +The `triggers` argument cannot be imported. +-- docs/ephemeral-resources/time_ephemeral_static.html.markdown -- +--- +layout: "time" +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +```hcl +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +``` + +### Triggers Usage + +```hcl +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +``` + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +```console +$ terraform import time_static.example 2020-02-12T06:36:13Z +``` + The `triggers` argument cannot be imported. -- exp-examples/example_1.tf -- resource "time_static" "ami_update" { @@ -661,6 +753,33 @@ resource "aws_instance" "server" { } -- exp-examples/resources/static/import_1.sh -- $ terraform import time_static.example 2020-02-12T06:36:13Z +-- exp-examples/ephemeral-resources/ephemeral_static/example_1.tf -- +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +-- exp-examples/ephemeral-resources/ephemeral_static/example_2.tf -- +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +-- exp-examples/ephemeral-resources/ephemeral_static/import_1.sh -- +$ terraform import time_static.example 2020-02-12T06:36:13Z -- exp-templates/index.md.tmpl -- --- page_title: "Provider: Time" @@ -961,4 +1080,59 @@ This resource can be imported using the UTC RFC3339 value, e.g. {{codefile "shell" "examples/resources/static/import_1.sh"}} +The `triggers` argument cannot be imported. +-- exp-templates/ephemeral-resources/ephemeral_static.md.tmpl -- +--- +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates. + +For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}} + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_1.tf"}} + +### Triggers Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_2.tf"}} + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +{{codefile "shell" "examples/ephemeral-resources/ephemeral_static/import_1.sh"}} + The `triggers` argument cannot be imported. \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_legacy_website.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_legacy_website.txtar index 736e2d3b..1b067803 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_legacy_website.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_legacy_website.txtar @@ -15,6 +15,7 @@ cmpenv templates/resources/offset.md.tmpl exp-templates/resources/offset.md.tmpl cmpenv templates/resources/rotating.md.tmpl exp-templates/resources/rotating.md.tmpl cmpenv templates/resources/sleep.md.tmpl exp-templates/resources/sleep.md.tmpl cmpenv templates/resources/static.md.tmpl exp-templates/resources/static.md.tmpl +cmpenv templates/ephemeral-resources/ephemeral_static.md.tmpl exp-templates/ephemeral-resources/ephemeral_static.md.tmpl # Check generated example files cmpenv examples/example_1.tf examples/example_1.tf @@ -35,16 +36,28 @@ cmpenv examples/resources/sleep/example_3.tf exp-examples/resources/sleep/exampl cmpenv examples/resources/sleep/import_1.sh exp-examples/resources/sleep/import_1.sh cmpenv examples/resources/sleep/import_2.sh exp-examples/resources/sleep/import_2.sh -cmpenv examples/resources/static/example_1.tf examples/resources/static/example_1.tf -cmpenv examples/resources/static/example_2.tf examples/resources/static/example_2.tf -cmpenv examples/resources/static/import_1.sh examples/resources/static/import_1.sh +cmpenv examples/resources/static/example_1.tf exp-examples/resources/static/example_1.tf +cmpenv examples/resources/static/example_2.tf exp-examples/resources/static/example_2.tf +cmpenv examples/resources/static/import_1.sh exp-examples/resources/static/import_1.sh + +cmpenv examples/ephemeral-resources/ephemeral_static/example_1.tf exp-examples/ephemeral-resources/ephemeral_static/example_1.tf +cmpenv examples/ephemeral-resources/ephemeral_static/example_2.tf exp-examples/ephemeral-resources/ephemeral_static/example_2.tf +cmpenv examples/ephemeral-resources/ephemeral_static/import_1.sh exp-examples/ephemeral-resources/ephemeral_static/import_1.sh # Verify legacy website directory is removed ! exists website/ -- expected-output.txt -- migrating website from "$WORK/website/docs" to "$WORK/templates" -migrating functons directory: functions +migrating ephemeral resources directory: ephemeral-resources +migrating file "ephemeral_static.html.markdown" +extracting YAML frontmatter to "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +extracting code examples from "ephemeral_static.html.markdown" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_1.tf" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_2.tf" +creating import file "$WORK/examples/ephemeral-resources/ephemeral_static/import_1.sh" +finished creating template "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +migrating functions directory: functions migrating file "rfc3339_parse.html.markdown" extracting YAML frontmatter to "$WORK/templates/functions/rfc3339_parse.md.tmpl" extracting code examples from "rfc3339_parse.html.markdown" @@ -518,7 +531,85 @@ $ terraform import time_static.example 2020-02-12T06:36:13Z ``` The `triggers` argument cannot be imported. +-- website/docs/ephemeral-resources/ephemeral_static.html.markdown -- +--- +layout: "time" +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +```hcl +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +``` + +### Triggers Usage + +```hcl +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +``` + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +```console +$ terraform import time_static.example 2020-02-12T06:36:13Z +``` +The `triggers` argument cannot be imported. -- exp-examples/example_1.tf -- resource "time_static" "ami_update" { triggers = { @@ -665,6 +756,33 @@ resource "aws_instance" "server" { } -- exp-examples/resources/static/import_1.sh -- $ terraform import time_static.example 2020-02-12T06:36:13Z +-- exp-examples/ephemeral-resources/ephemeral_static/example_1.tf -- +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +-- exp-examples/ephemeral-resources/ephemeral_static/example_2.tf -- +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +-- exp-examples/ephemeral-resources/ephemeral_static/import_1.sh -- +$ terraform import time_static.example 2020-02-12T06:36:13Z -- exp-templates/index.md.tmpl -- --- page_title: "Provider: Time" @@ -965,4 +1083,59 @@ This resource can be imported using the UTC RFC3339 value, e.g. {{codefile "shell" "examples/resources/static/import_1.sh"}} +The `triggers` argument cannot be imported. +-- exp-templates/ephemeral-resources/ephemeral_static.md.tmpl -- +--- +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates. + +For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}} + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_1.tf"}} + +### Triggers Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_2.tf"}} + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +{{codefile "shell" "examples/ephemeral-resources/ephemeral_static/import_1.sh"}} + The `triggers` argument cannot be imported. \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_legacy_website_with_prefix.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_legacy_website_with_prefix.txtar index 75f93373..e1ce2305 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_legacy_website_with_prefix.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/migrate/time_provider_success_legacy_website_with_prefix.txtar @@ -15,6 +15,7 @@ cmpenv templates/resources/offset.md.tmpl exp-templates/resources/offset.md.tmpl cmpenv templates/resources/rotating.md.tmpl exp-templates/resources/rotating.md.tmpl cmpenv templates/resources/sleep.md.tmpl exp-templates/resources/sleep.md.tmpl cmpenv templates/resources/static.md.tmpl exp-templates/resources/static.md.tmpl +cmpenv templates/ephemeral-resources/ephemeral_static.md.tmpl exp-templates/ephemeral-resources/ephemeral_static.md.tmpl # Check generated example files cmpenv examples/example_1.tf examples/example_1.tf @@ -35,16 +36,28 @@ cmpenv examples/resources/sleep/example_3.tf exp-examples/resources/sleep/exampl cmpenv examples/resources/sleep/import_1.sh exp-examples/resources/sleep/import_1.sh cmpenv examples/resources/sleep/import_2.sh exp-examples/resources/sleep/import_2.sh -cmpenv examples/resources/static/example_1.tf examples/resources/static/example_1.tf -cmpenv examples/resources/static/example_2.tf examples/resources/static/example_2.tf -cmpenv examples/resources/static/import_1.sh examples/resources/static/import_1.sh +cmpenv examples/resources/static/example_1.tf exp-examples/resources/static/example_1.tf +cmpenv examples/resources/static/example_2.tf exp-examples/resources/static/example_2.tf +cmpenv examples/resources/static/import_1.sh exp-examples/resources/static/import_1.sh + +cmpenv examples/ephemeral-resources/ephemeral_static/example_1.tf exp-examples/ephemeral-resources/ephemeral_static/example_1.tf +cmpenv examples/ephemeral-resources/ephemeral_static/example_2.tf exp-examples/ephemeral-resources/ephemeral_static/example_2.tf +cmpenv examples/ephemeral-resources/ephemeral_static/import_1.sh exp-examples/ephemeral-resources/ephemeral_static/import_1.sh # Verify legacy website directory is removed ! exists website/ -- expected-output.txt -- migrating website from "$WORK/website/docs" to "$WORK/templates" -migrating functons directory: functions +migrating ephemeral resources directory: ephemeral-resources +migrating file "time_ephemeral_static.html.markdown" +extracting YAML frontmatter to "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +extracting code examples from "time_ephemeral_static.html.markdown" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_1.tf" +creating example file "$WORK/examples/ephemeral-resources/ephemeral_static/example_2.tf" +creating import file "$WORK/examples/ephemeral-resources/ephemeral_static/import_1.sh" +finished creating template "$WORK/templates/ephemeral-resources/ephemeral_static.md.tmpl" +migrating functions directory: functions migrating file "time_rfc3339_parse.html.markdown" extracting YAML frontmatter to "$WORK/templates/functions/rfc3339_parse.md.tmpl" extracting code examples from "time_rfc3339_parse.html.markdown" @@ -518,7 +531,85 @@ $ terraform import time_static.example 2020-02-12T06:36:13Z ``` The `triggers` argument cannot be imported. +-- website/docs/ephemeral-resources/time_ephemeral_static.html.markdown -- +--- +layout: "time" +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +```hcl +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +``` + +### Triggers Usage + +```hcl +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +``` + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +```console +$ terraform import time_static.example 2020-02-12T06:36:13Z +``` +The `triggers` argument cannot be imported. -- exp-examples/example_1.tf -- resource "time_static" "ami_update" { triggers = { @@ -665,6 +756,33 @@ resource "aws_instance" "server" { } -- exp-examples/resources/static/import_1.sh -- $ terraform import time_static.example 2020-02-12T06:36:13Z +-- exp-examples/ephemeral-resources/ephemeral_static/example_1.tf -- +resource "time_static" "example" {} + +output "current_time" { + value = time_static.example.rfc3339 +} +-- exp-examples/ephemeral-resources/ephemeral_static/example_2.tf -- +resource "time_static" "ami_update" { + triggers = { + # Save the time each switch of an AMI id + ami_id = data.aws_ami.example.id + } +} + +resource "aws_instance" "server" { + # Read the AMI id "through" the time_static resource to ensure that + # both will change together. + ami = time_static.ami_update.triggers.ami_id + + tags = { + AmiUpdateTime = time_static.ami_update.rfc3339 + } + + # ... (other aws_instance arguments) ... +} +-- exp-examples/ephemeral-resources/ephemeral_static/import_1.sh -- +$ terraform import time_static.example 2020-02-12T06:36:13Z -- exp-templates/index.md.tmpl -- --- page_title: "Provider: Time" @@ -965,4 +1083,59 @@ This resource can be imported using the UTC RFC3339 value, e.g. {{codefile "shell" "examples/resources/static/import_1.sh"}} +The `triggers` argument cannot be imported. +-- exp-templates/ephemeral-resources/ephemeral_static.md.tmpl -- +--- +page_title: "Time: time_ephemeral_static" +description: |- + Manages a static time resource. +--- + +{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates. + +For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}} + +# Resource: time_static + +Manages a static time resource, which keeps a locally sourced UTC timestamp stored in the Terraform state. This prevents perpetual differences caused by using the [`timestamp()` function](https://www.terraform.io/docs/configuration/functions/timestamp.html). + +-> Further manipulation of incoming or outgoing values can be accomplished with the [`formatdate()` function](https://www.terraform.io/docs/configuration/functions/formatdate.html) and the [`timeadd()` function](https://www.terraform.io/docs/configuration/functions/timeadd.html). + +## Example Usage + +### Basic Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_1.tf"}} + +### Triggers Usage + +{{tffile "examples/ephemeral-resources/ephemeral_static/example_2.tf"}} + +## Argument Reference + +The following arguments are optional: + +* `triggers` - (Optional) Arbitrary map of values that, when changed, will trigger a new base timestamp value to be saved. See [the main provider documentation](../index.html) for more information. +* `rfc3339` - (Optional) Configure the base timestamp with an UTC [RFC3339 time string](https://tools.ietf.org/html/rfc3339#section-5.8) (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the current time. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `day` - Number day of timestamp. +* `hour` - Number hour of timestamp. +* `id` - UTC RFC3339 timestamp format, e.g. `2020-02-12T06:36:13Z`. +* `minute` - Number minute of timestamp. +* `month` - Number month of timestamp. +* `rfc3339` - UTC RFC3339 format of timestamp, e.g. `2020-02-12T06:36:13Z`. +* `second` - Number second of timestamp. +* `unix` - Number of seconds since epoch time, e.g. `1581489373`. +* `year` - Number year of timestamp. + +## Import + +This resource can be imported using the UTC RFC3339 value, e.g. + +{{codefile "shell" "examples/ephemeral-resources/ephemeral_static/import_1.sh"}} + The `triggers` argument cannot be imported. \ No newline at end of file diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_error_file_mismatch.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_error_file_mismatch.txtar index 8a0d2e19..e19a80b4 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_error_file_mismatch.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_error_file_mismatch.txtar @@ -5,10 +5,16 @@ [!unix] skip ! exec tfplugindocs validate --provider-name=terraform-provider-scaffolding --providers-schema=schema.json stderr 'Error executing command: validation errors found:' -stderr 'matching resource for documentation file \(resource2.md\) not found, file is extraneous or incorrectly named' +stderr 'matching resource for documentation file \(example2.md\) not found, file is extraneous or incorrectly named' stderr 'missing documentation file for resource: scaffolding_example' +stderr 'matching datasource for documentation file \(example2.md\) not found, file is extraneous or incorrectly named' +stderr 'missing documentation file for datasource: scaffolding_example' +stderr 'matching function for documentation file \(example2.md\) not found, file is extraneous or incorrectly named' +stderr 'missing documentation file for function: example' +stderr 'matching ephemeral resource for documentation file \(example2.md\) not found, file is extraneous or incorrectly named' +stderr 'missing documentation file for ephemeral resource: scaffolding_example' --- docs/data-sources/example.md -- +-- docs/data-sources/example2.md -- --- subcategory: "Example" page_title: "Example: example_thing" @@ -19,7 +25,29 @@ description: |- Name: {{.Name}} Type: {{.Type}} --- docs/resources/resource2.md -- +-- docs/resources/example2.md -- +--- +subcategory: "Example" +page_title: "Example: example_thing" +description: |- + Example description. +--- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +-- docs/ephemeral-resources/example2.md -- +--- +subcategory: "Example" +page_title: "Example: example_thing" +description: |- + Example description. +--- +# Data Fields + +Name: {{.Name}} +Type: {{.Type}} +-- docs/functions/example2.md -- --- subcategory: "Example" page_title: "Example: example_thing" @@ -80,6 +108,36 @@ Type: {{.Type}} } } }, + "ephemeral_resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example resource", + "description_kind": "markdown" + } + } + }, "data_source_schemas": { "scaffolding_example": { "version": 0, diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_success_legacy_docs.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_success_legacy_docs.txtar index c87edab2..fa9df60f 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_success_legacy_docs.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_success_legacy_docs.txtar @@ -13,6 +13,8 @@ running mixed directories check detected legacy website directory, running checks running invalid directories check on website/docs/d running file checks on website/docs/d/example.html.md +running invalid directories check on website/docs/ephemeral-resources +running file checks on website/docs/ephemeral-resources/example.html.md running invalid directories check on website/docs/functions running file checks on website/docs/functions/example.html.md running invalid directories check on website/docs/guides @@ -68,6 +70,18 @@ description: |- --- # Data Fields +Name: {{.Name}} +Type: {{.Type}} +-- website/docs/ephemeral-resources/example.html.md -- +--- +subcategory: "Example" +layout: "example" +page_title: "Example: example_thing" +description: |- + Example description. +--- +# Data Fields + Name: {{.Name}} Type: {{.Type}} -- website/docs/index.html.md -- @@ -131,6 +145,36 @@ Type: {{.Type}} } } }, + "ephemeral_resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example resource", + "description_kind": "markdown" + } + } + }, "data_source_schemas": { "scaffolding_example": { "version": 0, diff --git a/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_success_registry_docs.txtar b/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_success_registry_docs.txtar index 220a8c3b..5fc21654 100644 --- a/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_success_registry_docs.txtar +++ b/cmd/tfplugindocs/testdata/scripts/schema-json/validate/framework_provider_success_registry_docs.txtar @@ -13,6 +13,8 @@ running mixed directories check detected static docs directory, running checks running invalid directories check on docs/data-sources running file checks on docs/data-sources/example.md +running invalid directories check on docs/ephemeral-resources +running file checks on docs/ephemeral-resources/example.md running invalid directories check on docs/functions running file checks on docs/functions/example.md running invalid directories check on docs/guides @@ -74,6 +76,17 @@ description: |- --- # Data Fields +Name: {{.Name}} +Type: {{.Type}} +-- docs/ephemeral-resources/example.md -- +--- +subcategory: "Example" +page_title: "Example: example_thing" +description: |- + Example description. +--- +# Data Fields + Name: {{.Name}} Type: {{.Type}} -- schema.json -- @@ -126,6 +139,36 @@ Type: {{.Type}} } } }, + "ephemeral_resource_schemas": { + "scaffolding_example": { + "version": 0, + "block": { + "attributes": { + "configurable_attribute": { + "type": "string", + "description": "Example configurable attribute", + "description_kind": "markdown", + "optional": true + }, + "defaulted": { + "type": "string", + "description": "Example configurable attribute with default value", + "description_kind": "markdown", + "optional": true, + "computed": true + }, + "id": { + "type": "string", + "description": "Example identifier", + "description_kind": "markdown", + "computed": true + } + }, + "description": "Example resource", + "description_kind": "markdown" + } + } + }, "data_source_schemas": { "scaffolding_example": { "version": 0, diff --git a/go.mod b/go.mod index b5bb2240..57fd2989 100644 --- a/go.mod +++ b/go.mod @@ -19,6 +19,7 @@ require ( go.abhg.dev/goldmark/frontmatter v0.2.0 golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df golang.org/x/text v0.19.0 + gopkg.in/yaml.v3 v3.0.1 ) require ( @@ -53,5 +54,4 @@ require ( golang.org/x/sys v0.21.0 // indirect golang.org/x/tools v0.22.0 // indirect gopkg.in/yaml.v2 v2.3.0 // indirect - gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/internal/check/directory.go b/internal/check/directory.go index 17c16d42..15be21ca 100644 --- a/internal/check/directory.go +++ b/internal/check/directory.go @@ -13,17 +13,19 @@ import ( const ( CdktfIndexDirectory = `cdktf` - LegacyIndexDirectory = `website/docs` - LegacyDataSourcesDirectory = `d` - LegacyGuidesDirectory = `guides` - LegacyResourcesDirectory = `r` - LegacyFunctionsDirectory = `functions` - - RegistryIndexDirectory = `docs` - RegistryDataSourcesDirectory = `data-sources` - RegistryGuidesDirectory = `guides` - RegistryResourcesDirectory = `resources` - RegistryFunctionsDirectory = `functions` + LegacyIndexDirectory = `website/docs` + LegacyDataSourcesDirectory = `d` + LegacyEphemeralResourcesDirectory = `ephemeral-resources` + LegacyGuidesDirectory = `guides` + LegacyResourcesDirectory = `r` + LegacyFunctionsDirectory = `functions` + + RegistryIndexDirectory = `docs` + RegistryDataSourcesDirectory = `data-sources` + RegistryEphemeralResourcesDirectory = `ephemeral-resources` + RegistryGuidesDirectory = `guides` + RegistryResourcesDirectory = `resources` + RegistryFunctionsDirectory = `functions` // Terraform Registry Storage Limits // https://www.terraform.io/docs/registry/providers/docs.html#storage-limits @@ -35,6 +37,7 @@ const ( var ValidLegacyDirectories = []string{ LegacyIndexDirectory, LegacyIndexDirectory + "/" + LegacyDataSourcesDirectory, + LegacyIndexDirectory + "/" + LegacyEphemeralResourcesDirectory, LegacyIndexDirectory + "/" + LegacyGuidesDirectory, LegacyIndexDirectory + "/" + LegacyResourcesDirectory, LegacyIndexDirectory + "/" + LegacyFunctionsDirectory, @@ -43,6 +46,7 @@ var ValidLegacyDirectories = []string{ var ValidRegistryDirectories = []string{ RegistryIndexDirectory, RegistryIndexDirectory + "/" + RegistryDataSourcesDirectory, + RegistryIndexDirectory + "/" + RegistryEphemeralResourcesDirectory, RegistryIndexDirectory + "/" + RegistryGuidesDirectory, RegistryIndexDirectory + "/" + RegistryResourcesDirectory, RegistryIndexDirectory + "/" + RegistryFunctionsDirectory, @@ -59,6 +63,7 @@ var ValidCdktfLanguages = []string{ var ValidLegacySubdirectories = []string{ LegacyIndexDirectory, LegacyDataSourcesDirectory, + LegacyEphemeralResourcesDirectory, LegacyGuidesDirectory, LegacyResourcesDirectory, } @@ -66,6 +71,7 @@ var ValidLegacySubdirectories = []string{ var ValidRegistrySubdirectories = []string{ RegistryIndexDirectory, RegistryDataSourcesDirectory, + RegistryEphemeralResourcesDirectory, RegistryGuidesDirectory, RegistryResourcesDirectory, } diff --git a/internal/check/directory_test.go b/internal/check/directory_test.go index 95c6f8a7..b2432de5 100644 --- a/internal/check/directory_test.go +++ b/internal/check/directory_test.go @@ -11,7 +11,7 @@ import ( "github.com/bmatcuk/doublestar/v4" ) -var DocumentationGlobPattern = `{docs/index.*,docs/{,cdktf/}{data-sources,guides,resources,functions}/**/*,website/docs/**/*}` +var DocumentationGlobPattern = `{docs/index.*,docs/{,cdktf/}{data-sources,ephemeral-resources,guides,resources,functions}/**/*,website/docs/**/*}` func TestMixedDirectoriesCheck(t *testing.T) { t.Parallel() @@ -38,6 +38,13 @@ func TestMixedDirectoriesCheck(t *testing.T) { }, ExpectError: true, }, + "invalid mixed directories - registry ephemeral resource": { + ProviderFS: fstest.MapFS{ + "docs/ephemeral-resources/invalid.md": {}, + "website/docs/index.md": {}, + }, + ExpectError: true, + }, "invalid mixed directories - registry resource": { ProviderFS: fstest.MapFS{ "docs/resources/invalid.md": {}, @@ -66,6 +73,13 @@ func TestMixedDirectoriesCheck(t *testing.T) { }, ExpectError: true, }, + "invalid mixed directories - legacy ephemeral resource": { + ProviderFS: fstest.MapFS{ + "website/docs/ephemeral-resources/invalid.html.markdown": {}, + "docs/resources/thing.md": {}, + }, + ExpectError: true, + }, "invalid mixed directories - legacy resource": { ProviderFS: fstest.MapFS{ "website/docs/r/invalid.html.markdown": {}, diff --git a/internal/check/file_mismatch.go b/internal/check/file_mismatch.go index d65989fd..c53827d7 100644 --- a/internal/check/file_mismatch.go +++ b/internal/check/file_mismatch.go @@ -28,6 +28,8 @@ type FileMismatchOptions struct { FunctionEntries []os.DirEntry + EphemeralResourceEntries []os.DirEntry + Schema *tfjson.ProviderSchema } @@ -74,6 +76,11 @@ func (check *FileMismatchCheck) Run() error { result = errors.Join(result, err) } + if check.Options.EphemeralResourceEntries != nil { + err := check.ResourceFileMismatchCheck(check.Options.EphemeralResourceEntries, "ephemeral resource", check.Options.Schema.EphemeralResourceSchemas) + result = errors.Join(result, err) + } + return result } diff --git a/internal/provider/generate.go b/internal/provider/generate.go index d0c3c965..7df7b63d 100644 --- a/internal/provider/generate.go +++ b/internal/provider/generate.go @@ -58,6 +58,14 @@ var ( "functions/%s.html.markdown", "functions/%s.html.md", } + websiteEphemeralResourceFile = "ephemeral-resources/%s.md.tmpl" + websiteEphemeralResourceFallbackFile = "ephemeral-resources.md.tmpl" + websiteEphemeralResourceFileStaticCandidates = []string{ + "ephemeral-resources/%s.md", + "ephemeral-resources/%s.markdown", + "ephemeral-resources/%s.html.markdown", + "ephemeral-resources/%s.html.md", + } websiteProviderFile = "index.md.tmpl" websiteProviderFileStaticCandidates = []string{ "index.markdown", @@ -71,6 +79,7 @@ var ( "guides", "resources", "functions", + "ephemeral-resources", } managedWebsiteFiles = []string{ @@ -372,6 +381,42 @@ func (g *generator) generateMissingFunctionTemplate(functionName string) error { return nil } +func (g *generator) generateMissingEphemeralResourceTemplate(resourceName string) error { + templatePath := fmt.Sprintf(websiteEphemeralResourceFile, resourceShortName(resourceName, g.providerName)) + templatePath = filepath.Join(g.TempTemplatesDir(), templatePath) + if fileExists(templatePath) { + g.infof("ephemeral resource %q template exists, skipping", resourceName) + return nil + } + + fallbackTemplatePath := filepath.Join(g.TempTemplatesDir(), websiteEphemeralResourceFallbackFile) + if fileExists(fallbackTemplatePath) { + g.infof("ephemeral resource %q fallback template exists, creating template", resourceName) + err := cp(fallbackTemplatePath, templatePath) + if err != nil { + return fmt.Errorf("unable to copy fallback template for %q: %w", resourceName, err) + } + return nil + } + + for _, candidate := range websiteEphemeralResourceFileStaticCandidates { + candidatePath := fmt.Sprintf(candidate, resourceShortName(resourceName, g.providerName)) + candidatePath = filepath.Join(g.TempTemplatesDir(), candidatePath) + if fileExists(candidatePath) { + g.infof("ephemeral resource %q static file exists, skipping", resourceName) + return nil + } + } + + g.infof("generating new template for %q", resourceName) + err := writeFile(templatePath, string(defaultResourceTemplate)) + if err != nil { + return fmt.Errorf("unable to write template for %q: %w", resourceName, err) + } + + return nil +} + func (g *generator) generateMissingProviderTemplate() error { templatePath := filepath.Join(g.TempTemplatesDir(), websiteProviderFile) if fileExists(templatePath) { @@ -433,6 +478,18 @@ func (g *generator) generateMissingTemplates(providerSchema *tfjson.ProviderSche } } + g.infof("generating missing ephemeral resource content") + for name, schema := range providerSchema.EphemeralResourceSchemas { + if g.ignoreDeprecated && schema.Block.Deprecated { + continue + } + + err := g.generateMissingEphemeralResourceTemplate(name) + if err != nil { + return fmt.Errorf("unable to generate template for ephemeral resource %q: %w", name, err) + } + } + g.infof("generating missing provider content") err := g.generateMissingProviderTemplate() if err != nil { @@ -494,8 +551,11 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) e relDir, relFile := filepath.Split(rel) relDir = filepath.ToSlash(relDir) - // skip special top-level generic resource, data source, and function templates - if relDir == "" && (relFile == "resources.md.tmpl" || relFile == "data-sources.md.tmpl" || relFile == "functions.md.tmpl") { + // skip special top-level generic resource, data source, function, and ephemeral resource templates + if relDir == "" && (relFile == "resources.md.tmpl" || + relFile == "data-sources.md.tmpl" || + relFile == "functions.md.tmpl" || + relFile == "ephemeral-resources.md.tmpl") { return nil } @@ -579,6 +639,23 @@ func (g *generator) renderStaticWebsite(providerSchema *tfjson.ProviderSchema) e } g.warnf("function entitled %q does not exist", funcName) + case "ephemeral-resources/": + resSchema, resName := resourceSchema(providerSchema.EphemeralResourceSchemas, shortName, relFile) + exampleFilePath := filepath.Join(g.ProviderExamplesDir(), "ephemeral-resources", resName, "ephemeral-resource.tf") + + if resSchema != nil { + tmpl := resourceTemplate(tmplData) + render, err := tmpl.Render(g.providerDir, resName, g.providerName, g.renderedProviderName, "Ephemeral Resource", exampleFilePath, "", resSchema) + if err != nil { + return fmt.Errorf("unable to render ephemeral resource template %q: %w", rel, err) + } + _, err = out.WriteString(render) + if err != nil { + return fmt.Errorf("unable to write rendered string: %w", err) + } + return nil + } + g.warnf("ephemeral resource entitled %q, or %q does not exist", shortName, resName) case "": // provider if relFile == "index.md.tmpl" { tmpl := providerTemplate(tmplData) diff --git a/internal/provider/migrate.go b/internal/provider/migrate.go index babe2127..9abd7734 100644 --- a/internal/provider/migrate.go +++ b/internal/provider/migrate.go @@ -105,7 +105,7 @@ func (m *migrator) Migrate() error { if d.IsDir() { switch d.Name() { case "d", "data-sources": //data-sources - m.infof("migrating data-sources directory: %s", d.Name()) + m.infof("migrating datasources directory: %s", d.Name()) err := filepath.WalkDir(path, m.MigrateTemplate("data-sources")) if err != nil { return err @@ -119,12 +119,19 @@ func (m *migrator) Migrate() error { } return filepath.SkipDir case "functions": - m.infof("migrating functons directory: %s", d.Name()) + m.infof("migrating functions directory: %s", d.Name()) err := filepath.WalkDir(path, m.MigrateTemplate("functions")) if err != nil { return err } return filepath.SkipDir + case "ephemeral-resources": + m.infof("migrating ephemeral resources directory: %s", d.Name()) + err := filepath.WalkDir(path, m.MigrateTemplate("ephemeral-resources")) + if err != nil { + return err + } + return filepath.SkipDir case "guides": m.infof("copying guides directory: %s", d.Name()) err := cp(path, filepath.Join(m.ProviderTemplatesDir(), "guides")) diff --git a/internal/provider/testdata/schema.json b/internal/provider/testdata/schema.json index 868bae22..48876497 100644 --- a/internal/provider/testdata/schema.json +++ b/internal/provider/testdata/schema.json @@ -34,6 +34,32 @@ } } }, + "ephemeral_resource_schemas": { + "null_ephemeral_resource": { + "version": 0, + "block": { + "attributes": { + "id": { + "type": "string", + "description": "This is set to a random value at create time.", + "description_kind": "plain", + "computed": true + }, + "triggers": { + "type": [ + "map", + "string" + ], + "description": "A map of arbitrary strings that, when changed, will force the null resource to be replaced, re-running any associated provisioners.", + "description_kind": "plain", + "optional": true + } + }, + "description": "The `null_resource` resource implements the standard resource lifecycle but takes no further action.\n\nThe `triggers` argument allows specifying an arbitrary set of values that, when changed, will cause the resource to be replaced.", + "description_kind": "plain" + } + } + }, "data_source_schemas": { "null_data_source": { "version": 0, @@ -83,6 +109,25 @@ "deprecated": true } } + }, + "functions": { + "null": { + "description": "Given a string value, returns the same value.", + "summary": "Echo a string", + "return_type": "string", + "parameters": [ + { + "name": "input", + "description": "Value to echo.", + "type": "string" + } + ], + "variadic_parameter": { + "name": "variadicInput", + "description": "Variadic input to echo.", + "type": "string" + } + } } } } diff --git a/internal/provider/util_test.go b/internal/provider/util_test.go index 95e59b84..0e04f13e 100644 --- a/internal/provider/util_test.go +++ b/internal/provider/util_test.go @@ -106,11 +106,19 @@ func Test_extractSchemaFromFile(t *testing.T) { if providerSchema.DataSourceSchemas["null_data_source"] == nil { t.Fatalf("null_data_source not found") } + if providerSchema.Functions["null"] == nil { + t.Fatalf("null function not found") + } + if providerSchema.EphemeralResourceSchemas["null_ephemeral_resource"] == nil { + t.Fatalf("null_ephemeral_resource not found") + } if providerSchema.ResourceSchemas["null_resource"].Block.Attributes["id"] == nil { t.Fatalf("null_resoruce id attribute not found") } if providerSchema.DataSourceSchemas["null_data_source"].Block.Attributes["id"] == nil { t.Fatalf("null_data_source id attribute not found") } - + if providerSchema.EphemeralResourceSchemas["null_ephemeral_resource"].Block.Attributes["id"] == nil { + t.Fatalf("null_ephemeral_resoruce id attribute not found") + } } diff --git a/internal/provider/validate.go b/internal/provider/validate.go index f7751a0b..0ba0fd21 100644 --- a/internal/provider/validate.go +++ b/internal/provider/validate.go @@ -25,8 +25,8 @@ const ( FileExtensionMarkdown = `.markdown` FileExtensionMd = `.md` - DocumentationGlobPattern = `{docs/index.*,docs/{,cdktf/}{data-sources,guides,resources,functions}/**/*,website/docs/**/*}` - DocumentationDirGlobPattern = `{docs/{,cdktf/}{data-sources,guides,resources,functions}{,/*},website/docs/**/*}` + DocumentationGlobPattern = `{docs/index.*,docs/{,cdktf/}{data-sources,ephemeral-resources,guides,resources,functions}/**/*,website/docs/**/*}` + DocumentationDirGlobPattern = `{docs/{,cdktf/}{data-sources,ephemeral-resources,guides,resources,functions}{,/*},website/docs/**/*}` ) var ValidLegacyFileExtensions = []string{ @@ -253,6 +253,10 @@ func (v *validator) validateStaticDocs() error { functionFiles, _ := fs.ReadDir(v.providerFS, dir+"/functions") mismatchOpt.FunctionEntries = functionFiles } + if dirExists(v.providerFS, dir+"/ephemeral-resources") { + ephemeralResourceFiles, _ := fs.ReadDir(v.providerFS, dir+"/ephemeral-resources") + mismatchOpt.EphemeralResourceEntries = ephemeralResourceFiles + } v.logger.infof("running file mismatch check") if err := check.NewFileMismatchCheck(mismatchOpt).Run(); err != nil { @@ -332,6 +336,10 @@ func (v *validator) validateLegacyWebsite() error { functionFiles, _ := fs.ReadDir(v.providerFS, dir+"/functions") mismatchOpt.FunctionEntries = functionFiles } + if dirExists(v.providerFS, dir+"/ephemeral-resources") { + ephemeralResourceFiles, _ := fs.ReadDir(v.providerFS, dir+"/ephemeral-resources") + mismatchOpt.EphemeralResourceEntries = ephemeralResourceFiles + } v.logger.infof("running file mismatch check") if err := check.NewFileMismatchCheck(mismatchOpt).Run(); err != nil { diff --git a/internal/provider/validate_test.go b/internal/provider/validate_test.go index a6ada21d..03de43a3 100644 --- a/internal/provider/validate_test.go +++ b/internal/provider/validate_test.go @@ -81,6 +81,9 @@ func TestValidateStaticDocs_DirectoryChecks(t *testing.T) { "docs/data-sources/thing.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, + "docs/ephemeral-resources/thing.md": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, "docs/functions/thing.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, @@ -106,6 +109,9 @@ func TestValidateStaticDocs_DirectoryChecks(t *testing.T) { "docs/cdktf/typescript/data-sources/thing.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, + "docs/cdktf/typescript/ephemeral-resources/thing.md": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, "docs/cdktf/typescirpt/guides/thing.md": { Data: encodeYAML(t, &ValidRegistryGuideFrontMatter), }, @@ -146,6 +152,9 @@ func TestValidateStaticDocs_DirectoryChecks(t *testing.T) { "docs/data-sources/invalid/thing.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, + "docs/ephemeral-resources/invalid/thing.md": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, "docs/guides/invalid/thing.md": { Data: encodeYAML(t, &ValidRegistryGuideFrontMatter), }, @@ -166,6 +175,7 @@ func TestValidateStaticDocs_DirectoryChecks(t *testing.T) { }, }, ExpectedError: "invalid Terraform Provider documentation directory found: " + filepath.Join("docs", "data-sources", "invalid") + + "\ninvalid Terraform Provider documentation directory found: " + filepath.Join("docs", "ephemeral-resources", "invalid") + "\ninvalid Terraform Provider documentation directory found: " + filepath.Join("docs", "functions", "invalid") + "\ninvalid Terraform Provider documentation directory found: " + filepath.Join("docs", "guides", "invalid") + "\ninvalid Terraform Provider documentation directory found: " + filepath.Join("docs", "resources", "invalid"), @@ -235,6 +245,38 @@ func TestValidateStaticDocs_FileChecks(t *testing.T) { filepath.Join("docs", "data-sources", "with_layout.md") + ": error checking file frontmatter: YAML frontmatter should not contain layout\n" + filepath.Join("docs", "data-sources", "with_sidebar_current.md") + ": error checking file frontmatter: YAML frontmatter should not contain sidebar_current", }, + "invalid ephemeral resource files": { + ProviderFS: fstest.MapFS{ + "docs/ephemeral-resources/invalid_extension.txt": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, + "docs/ephemeral-resources/invalid_frontmatter.md": &InvalidYAMLFrontMatter, + "docs/ephemeral-resources/with_layout.md": { + Data: encodeYAML(t, + &FrontMatterData{ + Layout: &exampleLayout, + Subcategory: &exampleSubcategory, + PageTitle: &examplePageTitle, + Description: &exampleDescription, + }, + ), + }, + "docs/ephemeral-resources/with_sidebar_current.md": { + Data: encodeYAML(t, + &FrontMatterData{ + SidebarCurrent: &exampleSidebarCurrent, + Subcategory: &exampleSubcategory, + PageTitle: &examplePageTitle, + Description: &exampleDescription, + }, + ), + }, + }, + ExpectedError: filepath.Join("docs", "ephemeral-resources", "invalid_extension.txt") + ": error checking file extension: file does not end with a valid extension, valid extensions: [.md]\n" + + filepath.Join("docs", "ephemeral-resources", "invalid_frontmatter.md") + ": error checking file frontmatter: error parsing YAML frontmatter: yaml: line 4: could not find expected ':'\n" + + filepath.Join("docs", "ephemeral-resources", "with_layout.md") + ": error checking file frontmatter: YAML frontmatter should not contain layout\n" + + filepath.Join("docs", "ephemeral-resources", "with_sidebar_current.md") + ": error checking file frontmatter: YAML frontmatter should not contain sidebar_current", + }, "invalid resource files": { ProviderFS: fstest.MapFS{ "docs/resources/invalid_extension.txt": { @@ -403,6 +445,9 @@ func TestValidateStaticDocs_FileMismatchCheck(t *testing.T) { DataSourceSchemas: map[string]*tfjson.Schema{ "test_pet": {}, }, + EphemeralResourceSchemas: map[string]*tfjson.Schema{ + "test_ephemeral_id": {}, + }, ResourceSchemas: map[string]*tfjson.Schema{ "test_id": {}, }, @@ -414,6 +459,9 @@ func TestValidateStaticDocs_FileMismatchCheck(t *testing.T) { "docs/data-sources/pet.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, + "docs/ephemeral-resources/ephemeral_id.md": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, "docs/functions/parse_id.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, @@ -428,6 +476,10 @@ func TestValidateStaticDocs_FileMismatchCheck(t *testing.T) { "test_pet": {}, "test_pet2": {}, }, + EphemeralResourceSchemas: map[string]*tfjson.Schema{ + "test_ephemeral_id": {}, + "test_ephemeral_id2": {}, + }, ResourceSchemas: map[string]*tfjson.Schema{ "test_id": {}, "test_id2": {}, @@ -441,6 +493,9 @@ func TestValidateStaticDocs_FileMismatchCheck(t *testing.T) { "docs/data-sources/pet.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, + "docs/ephemeral-resources/ephemeral_id.md": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, "docs/functions/parse_id.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, @@ -450,13 +505,17 @@ func TestValidateStaticDocs_FileMismatchCheck(t *testing.T) { }, ExpectedError: "missing documentation file for resource: test_id2\n" + "missing documentation file for datasource: test_pet2\n" + - "missing documentation file for function: parse_id2", + "missing documentation file for function: parse_id2\n" + + "missing documentation file for ephemeral resource: test_ephemeral_id2", }, "invalid - extra files": { ProviderSchema: &tfjson.ProviderSchema{ DataSourceSchemas: map[string]*tfjson.Schema{ "test_pet": {}, }, + EphemeralResourceSchemas: map[string]*tfjson.Schema{ + "test_ephemeral_id": {}, + }, ResourceSchemas: map[string]*tfjson.Schema{ "test_id": {}, }, @@ -471,6 +530,12 @@ func TestValidateStaticDocs_FileMismatchCheck(t *testing.T) { "docs/data-sources/pet2.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, + "docs/ephemeral-resources/ephemeral_id.md": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, + "docs/ephemeral-resources/ephemeral_id2.md": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, "docs/functions/parse_id.md": { Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), }, @@ -486,7 +551,8 @@ func TestValidateStaticDocs_FileMismatchCheck(t *testing.T) { }, ExpectedError: "matching resource for documentation file (id2.md) not found, file is extraneous or incorrectly named\n" + "matching datasource for documentation file (pet2.md) not found, file is extraneous or incorrectly named\n" + - "matching function for documentation file (parse_id2.md) not found, file is extraneous or incorrectly named", + "matching function for documentation file (parse_id2.md) not found, file is extraneous or incorrectly named\n" + + "matching ephemeral resource for documentation file (ephemeral_id2.md) not found, file is extraneous or incorrectly named", }, } @@ -527,6 +593,9 @@ func TestValidateLegacyWebsite_DirectoryChecks(t *testing.T) { "website/docs/d/thing.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, + "website/docs/ephemeral-resources/thing.html.markdown": { + Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), + }, "website/docs/functions/thing.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, @@ -546,6 +615,9 @@ func TestValidateLegacyWebsite_DirectoryChecks(t *testing.T) { "website/docs/cdktf/typescript/d/thing.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, + "website/docs/cdktf/typescript/ephemeral-resources/thing.html.markdown": { + Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), + }, "website/docs/cdktf/typescript/guides/thing.html.markdown": { Data: encodeYAML(t, &ValidLegacyGuideFrontMatter), }, @@ -574,6 +646,9 @@ func TestValidateLegacyWebsite_DirectoryChecks(t *testing.T) { "website/docs/d/invalid/thing.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, + "website/docs/ephemeral-resources/invalid/thing.html.markdown": { + Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), + }, "website/docs/functions/invalid/thing.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, @@ -588,6 +663,7 @@ func TestValidateLegacyWebsite_DirectoryChecks(t *testing.T) { }, }, ExpectedError: "invalid Terraform Provider documentation directory found: " + filepath.Join("website", "docs", "d", "invalid") + + "\ninvalid Terraform Provider documentation directory found: " + filepath.Join("website", "docs", "ephemeral-resources", "invalid") + "\ninvalid Terraform Provider documentation directory found: " + filepath.Join("website", "docs", "functions", "invalid") + "\ninvalid Terraform Provider documentation directory found: " + filepath.Join("website", "docs", "guides", "invalid") + "\ninvalid Terraform Provider documentation directory found: " + filepath.Join("website", "docs", "r", "invalid"), @@ -657,6 +733,38 @@ func TestValidateLegacyWebsite_FileChecks(t *testing.T) { filepath.Join("website", "docs", "d", "with_sidebar_current.html.markdown") + ": error checking file frontmatter: YAML frontmatter should not contain sidebar_current\n" + filepath.Join("website", "docs", "d", "without_layout.html.markdown") + ": error checking file frontmatter: YAML frontmatter missing required layout", }, + "invalid ephemeral resource files": { + ProviderFS: fstest.MapFS{ + "website/docs/ephemeral-resources/invalid_extension.txt": { + Data: encodeYAML(t, &ValidRegistryResourceFrontMatter), + }, + "website/docs/ephemeral-resources/invalid_frontmatter.html.markdown": &InvalidYAMLFrontMatter, + "website/docs/ephemeral-resources/without_layout.html.markdown": { + Data: encodeYAML(t, + &FrontMatterData{ + Subcategory: &exampleSubcategory, + PageTitle: &examplePageTitle, + Description: &exampleDescription, + }, + ), + }, + "website/docs/ephemeral-resources/with_sidebar_current.html.markdown": { + Data: encodeYAML(t, + &FrontMatterData{ + SidebarCurrent: &exampleSidebarCurrent, + Subcategory: &exampleSubcategory, + Layout: &exampleLayout, + PageTitle: &examplePageTitle, + Description: &exampleDescription, + }, + ), + }, + }, + ExpectedError: filepath.Join("website", "docs", "ephemeral-resources", "invalid_extension.txt") + ": error checking file extension: file does not end with a valid extension, valid extensions: [.html.markdown .html.md .markdown .md]\n" + + filepath.Join("website", "docs", "ephemeral-resources", "invalid_frontmatter.html.markdown") + ": error checking file frontmatter: error parsing YAML frontmatter: yaml: line 4: could not find expected ':'\n" + + filepath.Join("website", "docs", "ephemeral-resources", "with_sidebar_current.html.markdown") + ": error checking file frontmatter: YAML frontmatter should not contain sidebar_current\n" + + filepath.Join("website", "docs", "ephemeral-resources", "without_layout.html.markdown") + ": error checking file frontmatter: YAML frontmatter missing required layout", + }, "invalid resource files": { ProviderFS: fstest.MapFS{ "website/docs/r/invalid_extension.txt": { @@ -833,6 +941,9 @@ func TestValidateLegacyWebsite_FileMismatchCheck(t *testing.T) { DataSourceSchemas: map[string]*tfjson.Schema{ "test_pet": {}, }, + EphemeralResourceSchemas: map[string]*tfjson.Schema{ + "test_ephemeral_id": {}, + }, ResourceSchemas: map[string]*tfjson.Schema{ "test_id": {}, }, @@ -844,6 +955,9 @@ func TestValidateLegacyWebsite_FileMismatchCheck(t *testing.T) { "website/docs/d/pet.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, + "website/docs/ephemeral-resources/ephemeral_id.html.markdown": { + Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), + }, "website/docs/functions/parse_id.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, @@ -858,6 +972,10 @@ func TestValidateLegacyWebsite_FileMismatchCheck(t *testing.T) { "test_pet": {}, "test_pet2": {}, }, + EphemeralResourceSchemas: map[string]*tfjson.Schema{ + "test_ephemeral_id": {}, + "test_ephemeral_id2": {}, + }, ResourceSchemas: map[string]*tfjson.Schema{ "test_id": {}, "test_id2": {}, @@ -871,6 +989,9 @@ func TestValidateLegacyWebsite_FileMismatchCheck(t *testing.T) { "website/docs/d/pet.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, + "website/docs/ephemeral-resources/ephemeral_id.html.markdown": { + Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), + }, "website/docs/functions/parse_id.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, @@ -880,13 +1001,17 @@ func TestValidateLegacyWebsite_FileMismatchCheck(t *testing.T) { }, ExpectedError: "missing documentation file for resource: test_id2\n" + "missing documentation file for datasource: test_pet2\n" + - "missing documentation file for function: parse_id2", + "missing documentation file for function: parse_id2\n" + + "missing documentation file for ephemeral resource: test_ephemeral_id2", }, "invalid - extra files": { ProviderSchema: &tfjson.ProviderSchema{ DataSourceSchemas: map[string]*tfjson.Schema{ "test_pet": {}, }, + EphemeralResourceSchemas: map[string]*tfjson.Schema{ + "test_ephemeral_id": {}, + }, ResourceSchemas: map[string]*tfjson.Schema{ "test_id": {}, }, @@ -901,6 +1026,12 @@ func TestValidateLegacyWebsite_FileMismatchCheck(t *testing.T) { "website/docs/d/pet2.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, + "website/docs/ephemeral-resources/ephemeral_id.html.markdown": { + Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), + }, + "website/docs/ephemeral-resources/ephemeral_id2.html.markdown": { + Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), + }, "website/docs/functions/parse_id.html.markdown": { Data: encodeYAML(t, &ValidLegacyResourceFrontMatter), }, @@ -916,7 +1047,8 @@ func TestValidateLegacyWebsite_FileMismatchCheck(t *testing.T) { }, ExpectedError: "matching resource for documentation file (id2.html.markdown) not found, file is extraneous or incorrectly named\n" + "matching datasource for documentation file (pet2.html.markdown) not found, file is extraneous or incorrectly named\n" + - "matching function for documentation file (parse_id2.html.markdown) not found, file is extraneous or incorrectly named", + "matching function for documentation file (parse_id2.html.markdown) not found, file is extraneous or incorrectly named\n" + + "matching ephemeral resource for documentation file (ephemeral_id2.html.markdown) not found, file is extraneous or incorrectly named", }, }