Generating sample usage

[pkaeding]

I'm experimenting with generating a sample usage section. I am pretty close, with this:

content: |
    {{ .Header }}

    ## Usage

    ```
    module "ec2_agent_status_data" {
      {{ "  " }}source = "[email protected]:org/repo//resources/{{ .ModuleName }}?ref={{ .ModuleName }}/<version>"
      {{ range .Module.Inputs }}
        {{ "  " }}# {{ .Description }}
        {{ "  " }}{{if not .Required }}#{{ end }}{{ .Name }} = {{if .Required }}???{{ else }}{{ .Default.Raw }}{{ end }}
      {{ end }}  
    }
    ```

But, I'm wondering what I can do with the ModuleName thing. I don't expect terraform-docs to be able to determine this, but I'd like to be able to pass it (or any arbitrary key/value string pair) to it, to be used in a custom content template like this.

Is this possible? Has anyone done anything like this before?

[rquadling]

This would be similar to what is produced on the Terraform Registry for modules. For example: https://registry.terraform.io/modules/digitickets/cli/aws/latest

But better.

The obvious cheat answer is to have a separately maintained example that gets included. But that's double maintenance.

From what I can tell (beginner here so use a pinch of salt), there is no easy way to know if the Terraform .tf files relate to a module or not. If there is, the library that reads the .tf files (and whatever else it reads) (Hashicorp's official library, my fork with input validations), there's nothing in it to help.

I think without something to act as a trigger to say the .tf code is a module, and that trigger being a recognised standard thing accessible via terraform-config-inspect, it would be guess work.

What may be the best option is to write the template in a standard form for modules to have. And so you just "drop in" the template in modules and terraform-docs uses that as standard.

Adding an option to terraform-docs for --show-module-call ... that could be done. A LOT of templates and examples and tests to modify for this though (having just added input validations and changing nearly everything in the repo!).