Description
What problem are you facing?
https://terraform-docs.io/how-to/include-examples/
Sometimes the example/main.tf
file has a lot of boilerplate used to setup a module/resource declaration. This is required for the code, but often to verbose for a snippet for a README document.
Consider the aws instance resource. The example in the documentation looks something like this:
data "aws_ami" "ubuntu" {
most_recent = true
filter {
name = "name"
values = ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"]
}
filter {
name = "virtualization-type"
values = ["hvm"]
}
owners = ["099720109477"] # Canonical
}
resource "aws_instance" "web" {
ami = data.aws_ami.ubuntu.id
instance_type = "t3.micro"
tags = {
Name = "HelloWorld"
}
}
This could be trimmed down for the sake of brevity
resource "aws_instance" "web" {
ami = data.aws_ami.ubuntu.id
instance_type = "t3.micro"
tags = {
Name = "HelloWorld"
}
}
The README would remain specific whilst the example/main.tf
code would maintain the complete set of boilerplate terraform.
How could terraform-docs help solve your problem?
It would be great if the include examples functionality could select a subset of lines from an example file. This might work similar to Github's select multiple lines of code feature
The .terraform-docs.yml
could look something like this.
# .terraform-docs.yml
content: |-
{{ .Header }}
## Example
```hcl
{{ include "examples/example-1/main.tf#L10-L50" }}
where L10
is the first line and L50
is the last line to include.
{{ .Inputs }}
{{ .Outputs }}
### Alternative
You could refactor the example such that the `main.tf` only contains the snippet you would like to include in the README, but then we are forced to format our examples in unfavorable ways to make the docs work.