Add an Examples section to automatically pull in module examples

[Varantha]

Description of your changes

Description

Adding an Examples section into the tool. The purpose being that if you have a list of examples in a subfolder in your Terraform module repository it will automatically find them and insert them into your documentation.

For example, I've now added an example to the example module here:
examples/examples/exampleA/main.tf

This takes the modules name (folder name) exampleA and its content (the file contents) and will display it as an additional section if configured to do so. It will take all folder names from 1 level below the examples folder, so long as that folder has a main.tf file present.

Added Config

Some extra config has been added to support this change.

examples-from: Following the style of footer-from and header-from, the location to take the examples from. This should point to the folder containing module folders. The default value is ./examples (aligning with Terraform's Standard Module Structure)

section > hide/show: Adding examples to the hide and show functionality. Example's default state is being hidden to avoid this change being disruptive

examples > include: A list of strings for what examples to include. These strings match the names of the example, in this case you would put:

include:
    - exampleA

To include the example in this project. All examples will be shown if neither include or exclude are set.

examples > exclude: A list of strings for what examples to exclude. This is the same functionality as include but in reverse. (attempting to match show / hide)

examples > limit: An integer for the maximum number of examples to show. If a project has too many examples then you might want to limit them and at scale you may not be able to include specific examples by name. This takes the first x examples in lexicographic order. If the value is set to 0 then all examples will be shown. The default is 0.

examples > HideTitles: By default, in formats like markdown and ascii it will show the title of the example as a header above it. e.g.

## Examples

### exampleA

```hcl
module full-example{
    source = "github.com/terraform-docs/terraform-docs//examples"
...

but this can be set to true to hide the title such that it is just:

## Examples

```hcl
module full-example{
    source = "github.com/terraform-docs/terraform-docs//examples"
...

Documentation

I'm very happy to update the documentation along with this change but I wanted to gauge interest in the feature / the config setting before continuing with it. (as it may change) Please let me know your thoughts on this and I'll start work on it.

Fixes #685
Fixes #617 (Not mine, but confident it's the same purpose)
Possibly #599 / #605 (Not my issues and unsure if it 100% meets their needs)
I have:

• Read and followed terraform-docs' [contribution process].
• All tests pass when I run make test.

How has this code been tested

I've added a whole suite of tests /updated tests in for every type of output which support examples and am confident that it has functionality in those areas. I've installed this branch locally and have applied it to some of my local projects without issue and have been messing around with the configuration file / combinations of configurations. Happy for feedback on any tests that could be added / edge cases you would like testing, but it seems good for standard use.

I would be interested for feedback for the more unique formats. I've updated the tests and tried to match the general style of format like pretty / toml / json, but these are typically not my use-cases so I can't say that they are ideally formatted in those areas.

[rquadling]

For more complex modules, examples are a VERY useful feature. Just as within a provider, not all properties are needed if one of the properties has a value, so, rather than JUST documenting that in each variable, worked examples, which may end up being copy'n'pasted by some, is a clear outline of the expected use of a module.