Skip to content

Commit 5db5509

Browse files
austinvalleaustinvalle
authored
generate: Add support for import configuration examples with identity + schema (#496)
* quick impl * add ID prefix * template update * add changelog * add import shell test * update acceptance tests and add some import config files * wip implementation * quick impl * add ID prefix * template update * add changelog * add import shell test * update acceptance tests and add some import config files * update naming * update changelog * change name * always provider identity schema in render * add a generate test * documentation * example * add acceptance tests * add more tests for render * add note about import changes * update PR number
1 parent 3b9b212 commit 5db5509

16 files changed

+773
-142
lines changed

‎.changes/unreleased/BREAKING CHANGES-20250613-135104.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
kind: BREAKING CHANGES
22
body: 'generate: The `.ProviderShortName` template function now uses the rendered provider name to derive the provider short name. Users that pass in the
3-
`--rendered-provider-name` flag might see a different output for this function'
3+
`--rendered-provider-name` flag might see a different output for this function'
44
time: 2025-06-13T13:51:04.745115-04:00
55
custom:
66
Issue: "492"

‎.changes/unreleased/FEATURES-20250625-173710.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
kind: FEATURES
2+
body: 'generate: Added support for defining import example file (`import-by-identity.tf`) using Terraform configuration
3+
and the `identity` attribute (managed resource identity)'
4+
time: 2025-06-25T17:37:10.853795-04:00
5+
custom:
6+
Issue: "496"

‎.changes/unreleased/NOTES-20250630-144026.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
kind: NOTES
2+
body: 'generate: Generated import documentation will now contain more information about which methods are
3+
supported by the provider (CLI command, config by ID, config by identity).'
4+
time: 2025-06-30T14:40:26.94407-04:00
5+
custom:
6+
Issue: "495"

‎README.md

Lines changed: 76 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -223,16 +223,17 @@ For examples:
223223
> **NOTE:** In the following conventional paths for examples, `<data source name>` and `<resource name>` include the provider prefix as well, but the provider prefix is **NOT** included in`<function name>`.
224224
> 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`
225225
226-
| Path | Description |
227-
|---------------------------------------------------------------------------|--------------------------------------|
228-
| `examples/` | Root of examples |
229-
| `examples/provider/provider.tf` | Provider example config |
230-
| `examples/data-sources/<data source name>/data-source.tf` | Data source example config |
231-
| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config |
232-
| `examples/functions/<function name>/function.tf` | Function example config |
233-
| `examples/resources/<resource name>/resource.tf` | Resource example config |
234-
| `examples/resources/<resource name>/import.sh` | Resource example import command |
235-
| `examples/resources/<resource name>/import-by-string-id.tf` | Resource example import by id config |
226+
| Path | Description |
227+
|---------------------------------------------------------------------------|--------------------------------------------|
228+
| `examples/` | Root of examples |
229+
| `examples/provider/provider.tf` | Provider example config |
230+
| `examples/data-sources/<data source name>/data-source.tf` | Data source example config |
231+
| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config |
232+
| `examples/functions/<function name>/function.tf` | Function example config |
233+
| `examples/resources/<resource name>/resource.tf` | Resource example config |
234+
| `examples/resources/<resource name>/import.sh` | Resource example import command |
235+
| `examples/resources/<resource name>/import-by-string-id.tf` | Resource example import by id config |
236+
| `examples/resources/<resource name>/import-by-identity.tf` | Resource example import by identity config |
236237
237238
#### Migration
238239
@@ -293,21 +294,24 @@ using the following data fields and functions:
293294
294295
##### Managed Resource / Ephemeral Resource / Data Source Fields
295296
296-
| Field | Type | Description |
297-
|-------------------------|--------|-------------------------------------------------------------------------------------------|
298-
| `.Name` | string | Name of the resource/data-source (ex. `tls_certificate`) |
299-
| `.Type` | string | Either `Resource` or `Data Source` |
300-
| `.Description` | string | Resource / Data Source description |
301-
| `.HasExample` | bool | Is there an example file? |
302-
| `.ExampleFile` | string | Path to the file with the terraform configuration example |
303-
| `.HasImport` | bool | Is there an import shell file? (`terraform import` shell example) |
304-
| `.ImportFile` | string | Path to the file with the command for importing the resource |
305-
| `.HasImportIDConfig` | bool | Is there an import terraform config file? (`import` block example with `id`) |
306-
| `.ImportIDConfigFile` | string | Path to the file with the Terraform configuration for importing the resource by `id` |
307-
| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) |
308-
| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) |
309-
| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
310-
| `.SchemaMarkdown` | string | a Markdown formatted Resource / Data Source Schema definition |
297+
| Field | Type | Description |
298+
|-----------------------------|--------|--------------------------------------------------------------------------------------------|
299+
| `.Name` | string | Name of the resource/data-source (ex. `tls_certificate`) |
300+
| `.Type` | string | Either `Resource` or `Data Source` |
301+
| `.Description` | string | Resource / Data Source description |
302+
| `.HasExample` | bool | Is there an example file? |
303+
| `.ExampleFile` | string | Path to the file with the terraform configuration example |
304+
| `.HasImport` | bool | Is there an import shell file? (`terraform import` shell example) |
305+
| `.ImportFile` | string | Path to the file with the command for importing the resource |
306+
| `.HasImportIDConfig` | bool | Is there an import terraform config file? (`import` block example with `id`) |
307+
| `.ImportIDConfigFile` | string | Path to the file with the Terraform configuration for importing the resource by `id` |
308+
| `.HasImportIdentityConfig` | bool | Is there an import terraform config file? (`import` block example with `identity`) |
309+
| `.ImportIdentityConfigFile` | string | Path to the file with the Terraform configuration for importing the resource by `identity` |
310+
| `.IdentitySchemaMarkdown` | string | a Markdown formatted Resource Identity Schema definition |
311+
| `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`) |
312+
| `.ProviderShortName` | string | Short version of the rendered provider name (ex. `random`) |
313+
| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
314+
| `.SchemaMarkdown` | string | a Markdown formatted Resource / Data Source Schema definition |
311315
312316
##### Provider-defined Function Fields
313317
@@ -360,16 +364,57 @@ This can be autogenerated by running `make generate` or running `go generate ./.
360364
### Acceptance Tests
361365

362366
This repo uses the `testscript` [package](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript) for acceptance testing.
363-
364367
There are two types of acceptance tests: full provider build tests in `tfplugindocs/testdata/scripts/provider-build` and provider schema json tests in `tfplugindocs/testdata/scripts/schema-json`.
365368

366-
Provider build tests run the default `tfplugindocs` command which builds the provider source code and runs Terraform to retrieve the schema. These tests require the full provider source code to build a valid provider binary.
367-
368-
Schema json tests run the `tfplugindocs` command with the `--providers-schema=<arg>` flag to specify a provider schemas json file. This allows the test to skip the provider build and Terraform CLI call, instead using the specified file to generate docs.
369+
Provider [build tests](./cmd/tfplugindocs/testdata/scripts/provider-build/) run the default `tfplugindocs` command which builds the provider source code and runs Terraform to retrieve the schema. These tests require the full provider source code to build a valid provider binary.
370+
[Schema json](./cmd/tfplugindocs/testdata/scripts/schema-json/) tests run the `tfplugindocs` command with the `--providers-schema=<arg>` flag to specify a provider schemas json file. This allows the test to skip the provider build and Terraform CLI call, instead using the specified file to generate docs.
369371

370372
You can run `make testacc` to run the full suite of acceptance tests. By default, the provider build acceptance tests will create a temporary directory in `/tmp/tftmp` for testing, but you can change this location in `cmd/tfplugindocs/main_test.go`. The schema json tests uses the `testscript` package's [default work directory](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript#Params.WorkdirRoot).
371373
372374
The test scripts are defined in the `tfplugindocs/testdata/scripts` directory. Each script includes the test, golden files, and the provider source code or schema JSON file needed to run the test.
375+
Each script is a [text archive](https://pkg.go.dev/golang.org/x/tools/txtar). You can install the `txtar` CLI locally by running `go install golang.org/x/exp/cmd/txtar@latest` to extract the files in the test script for debugging or to help with updating.
376+
377+
For example, to unarchive all of the files from a test script:
378+
```bash
379+
# Assuming that your working directory is the root of the terraform-plugin-docs repo
380+
381+
# Create a fresh directory to extract to
382+
mkdir tmp && cd tmp
383+
384+
# Extract this specific test script to the current working directory
385+
txtar -x <../cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar
386+
```
387+
388+
#### New test scripts
389+
390+
Updates to existing tests are typically just made manually, but the `txtar` CLI can be used to create a new test quickly.
391+
392+
A new text archive can be created from a folder with:
393+
```bash
394+
# Assuming that your working directory is the root of the terraform-plugin-docs repo
395+
396+
# Create a fresh directory to make changes to
397+
mkdir tmp && cd tmp
398+
399+
# Update files in ./tmp that you want in the new .txtar
400+
401+
# Archives all of the files in the current directory with a placeholder comment
402+
echo "placeholder comment" | txtar . >../cmd/tfplugindocs/testdata/scripts/provider-build/generate/new.txtar
403+
```
373404
374-
Each script is a [text archive](https://pkg.go.dev/golang.org/x/tools/txtar). You can install the `txtar` CLI locally by running `go install golang.org/x/exp/cmd/txtar@latest` to extract the files in the test script for debugging.
375-
You can also use `txtar` CLI archive files into the `.txtar` format to create new tests or modify existing ones.
405+
Once a new text archive is created, the comment header can be replaced with [test script commands](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript)
406+
like `env`, `cmp`, `exec`, etc. These commands control what actually is run during the test along with the assertions, for example:
407+
```bash
408+
# Copyright (c) HashiCorp, Inc.
409+
# SPDX-License-Identifier: MPL-2.0
410+
411+
# Successful run of tfplugindocs on a Framework provider with examples but no templates or pre-existing docs.
412+
[!unix] skip
413+
env GOCACHE=$WORK/gocache # sets an environment variable
414+
env GOMODCACHE=$WORK/gomodcache # sets an environment variable
415+
exec tfplugindocs --provider-name=terraform-provider-scaffolding # executes the Go binary for generating documentation
416+
cmp stdout expected-output.txt # compares stdout from binary with the golden file in the text archive below
417+
cmp docs/index.md expected-index.md # compares the generated docs with the golden file in the text archive below
418+
cmp docs/data-sources/example.md expected-datasource.md # compares the generated docs with the golden file in the text archive below
419+
cmp docs/resources/example.md expected-resource.md # compares the generated docs with the golden file in the text archive below
420+
```

0 commit comments

Comments
 (0)