Updating docs for child modules

[michelzanini]

What problem are you facing?

I am using pre-commit with terraform-docs with the hook provided by https://github.com/antonbabenko/pre-commit-terraform.

On that hook, it's possible to update all README.md files, including sub-modules of the root module. But that does seem to work if I were to switch to use this repo's new pre-commit hooks.

For example, consider this structure:

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

As you can see I have a root README.md for the root Terraform module, but also one or more sub-modules with their own README.md files. It would be nice to be able to update them all with a single run of pre-commit at the root level of the project.

How could terraform-docs help solve your problem?

Be able to run pre-commit hook or terraform-docs standalone and update root module AND sub-modules as well. This could be potentially enabled via a flag, named something like --include-sub-modules, --recursive or something else...

[khos2ow]

That's a really good suggestion. I like --recursive bool better, and to make it more flexible I like to add --recursive-path string (defaults to modules) to select submodules root folder.

That said, I'm not entirely sure this new feature can be used out of the box with antonbabenko/pre-commit-terraform right away due to different ways of saving the generated output to target files. Specifically the issue antonbabenko/pre-commit-terraform#179.

You can already use --output-file (and corresponding config) since v0.12.0, which will give us the ability to incorporate that with --recursive, but if you're not using terraform-docs' output and rely on pre-commit-terraform that means the --recursive needs to output to stdout and I cannot think of a reliable way pre-commit-terraform can pick up the output to inject (or replace) it in the correct submodule's target file (e.g. README.md).