Large amount of module documentation

[xunholy]

Hi, quick question;

How would you write, and operate a single repository with a large amount of modules when you want to generate a README per module?

Also additionally creating a top level README that includes all the modules recursively found in the repo - this would be sweet for users to find an easy way to navigate through the modules available.

[khos2ow]

@xunholy sorry for the long delay!

The easiest way (barring the edge cases) is to employ recursive functionality (either thorough config or CLI). Something like to update all the submodules' README and root README in one shot:

$ pwd
/path/to/module

$ tree .
.
├── README.md
├── main.tf
├── modules
│   └── my-sub-module
│       ├── README.md
│       ├── main.tf
│       ├── variables.tf
│       └── versions.tf
├── outputs.tf
├── variables.tf
└── versions.tf

$ terraform-docs markdown --recursive --output-file README.md .

But this is the most straightforward case, and based on your second question things can get a bit complicated. The reason is you want to have different content for root's README vs submodules' README.

As of now this is not possible (although this discussion gave me an idea, but not sure how feasible it will be,) but you can implement a workaround taking advantage of the fact if .terraform-docs.yml file is found in any submodule folder, it will override the main .terraform-docs.yml (partially or completely). So you can have a .terraform-docs.yml file at the root with all the sections hidden and special content, and one .terraform-docs.yml per modules with normal settings.

This might not be the most elegant way, since you already mentioned there is a large number of modules, but you can symlink a central config file for all the submodule folders.

[rquadling]

If you are using pre-commit, this config is what I have and what you are asking for is pretty much done automatically:

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.83.5
    hooks:
      - id: terraform_docs
        args:
          - --hook-config=--path-to-file=README.md
          - --hook-config=--add-to-existing-file=true
          - --hook-config=--create-file-if-not-exist=true

Strangely enough, the default for terraform-docs is to NOT recurse into modules.

But the running pre-commit run --all terraform_docs having just made module/peppers/variables.tf ends up creating module/peppers/README.md with:

# peppers

<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
## Requirements

No requirements.

## Providers

No providers.

## Modules

No modules.

## Resources

No resources.

## Inputs

| Name | Description | Type | Default | Required |
|------|-------------|------|---------|:--------:|
| <a name="input_empty_list"></a> [empty\_list](#input\_empty\_list) | The empty list | `list(string)` | `[]` | no |
| <a name="input_empty_set"></a> [empty\_set](#input\_empty\_set) | The empty set | `set(string)` | `[]` | no |

## Outputs

No outputs.
<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

So it looks like something is triggering it.