hashicorp / hashicorp/terraform-plugin-docs

Add a way to test that examples have a valid syntax

Open
#557 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Go
Stars
263
Forks
84
Avg merge
3d 6h
Merged PRs (30d)
2

Description

### Terraform CLI and terraform-plugin-docs Versions

```
❯ terraform version
Terraform v1.14.3
on darwin_arm64
```

```
github.com/hashicorp/terraform-plugin-docs v0.24.0 // indirect
```

### Use Cases or Problem Statement

We write examples that are then included in a template to generate the reference documentation.
But when we write an example there is no particular validation that is performed to ensure that an example is correct.
Also because all examples for a resource are living in the same folder we can have name collision if we have standard patterns. For instance calling a resource `main` or `example`. If several examples are in a folder and we try to run a `terraform validate` on the folder it will result in an error.

The problem would be, how to take each example individually, perform a terraform validate test on it to ensure it is correct?

### Proposal

Adding in the tfplugindocs a `validate-examples` command
This command will create temporary folder for each examples with a default provider defined.
Then it will run in parallel a terraform validate in each of this folder with no backend defined (we are only interested in checking the code is correct not actually running it)
Then it will give a diagnostic for each example file.
Then it will delete all temporary files.

### How much impact is this issue causing?

Medium

### Additional Information

This feature could be helpful to ensure that example don't mention deprecated features or attributes.

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.