What problem are you facing?

I want a better way to represent Examples in terraform-docs. The current method works however it can be a bit troublesome when scaling out. My particular use case is that I have many Terraform module repositories in a project within my company. When a new version is pushed it will automatically run terraform-docs to generate the documentation. If I want to add an Examples section to it, I must either ensure that every repo has an example in place or I would need to add some kind of logic to inject in the ##Examples string only if the file exists. This gets more complicated for multiple examples. I'm hoping to make a easier, more native way for people to include examples.

How could terraform-docs help solve your problem?

I propose adding a {{ .Examples }} content block that will have the default behaviour of iterating through examples/ and writing blocks for each main.tf found in child folders of examples with the subtitle ## Examples
E.g.

## Examples
```hcl
{{ include "examples/exampleA/main.tf" }}
```
```hcl
{{ include "examples/exampleB/main.tf" }}
```

This may or may not use the include function, this is just a representation of what it would do

If none of these files are found, no blocks would be created. Ideally the title will also be removed, but could also settle with "No Examples were found for this module".

Possible options for the block could be:

• Include / exclude options in case people want specific examples shown
• Come kind of filtering option for the examples (e.g. only taking certain lines numbers)

I'm hoping to do the legwork on this issue but I wanted to follow the guidelines to see if this is a desired change / if this is already underway at all.

Thanks :)

Credit to these issues which overlap / gave inspiration:
#617
#605
#599