terraform_docs: Check abillity to use native terraform-docs config as replacement for custom --hook-config=

[MaxymVlasov]

In #380 I discovered that terraform-docs now have a big config, that, theoretically, can be used as a replacement for all or part of custom --hook-config='s

Need to investigate that option, hope we can remove part of the custom logic.

[yermulnik]

In #380 I discovered that terraform-docs now have a big config

Me too 😂

that, theoretically, can be used as a replacement for all or part of custom --hook-config='s

...which would mean we need to ship pre-commit-terraform along with a terraform-docs config file, which consumers of pre-commit-terraform would need to amend per their preferences and requirements and put into a standard location where terraform-docs expect it to be (the precedence of config vs cmdline options is not obvious from the terraform-docs README file).
So this may suffice for dockerized pre-commit-terraform only, I seem to think (I might be wrong).
On the other hand, terraform-docs README says to use cmdline options when used with pre-commit: https://github.com/terraform-docs/terraform-docs#pre-commit-hook

[drAlberT]

I'm using the following hook configuration and everything related to terraform-doc is managed by the config files. It works like a charm but all the hook-config args (which are necessary to have it work) are totally useless as the same info is already present in the config file.

- repo: https://github.com/antonbabenko/pre-commit-terraform
   rev: v1.72.1
   hooks:
    - id: terraform_docs
       args:
         - --args=--config=infra/.terraform-docs.yml
         - --hook-config=--path-to-file=MODULE-DETAILS.md
         - --hook-config=--add-to-existing-file=false
         - --hook-config=--create-file-if-not-exist=true

[UkklyDukkling]

Adding my experience here using the .terraform-docs.yml config file with this hook. Generally passing in the config file works, however there is a slight bug that can produce some undesirable effects.

Example setup for various files:

Config file .pre-commit-config.yaml

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.81.0
    hooks:
      - id: terraform_docs
        args:
          - --args=--config=.terraform-docs.yml

Config file .terraform-docs.yml

formatter: "markdown"
version: "0.16.0"

content: |-
  {{ .Requirements }}
  ...
  various other customizations for our documentation
  ...

output:
  file: README.md
  mode: inject
  template: |-
    <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
    {{ .Content }}
    <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

# Truncated: "settings" block left as defaults for each option

Setup of README.md

# Title for repo

General description paragraph

<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

The Outcome

As you can see, the hook actually ends up writing the console message to the README.md file instead of the expected content.

Two things to note:

• If I remove the "output" block from my .terraform-docs.yml file, the content is correctly inserted into README.md. So far in my use case, all of the other configuration settings seem to work correctly. For my use case, I definitely want to retain the "output" block so more troubleshooting was necessary.
• If I keep the .terraform-docs-yml file target as README.md and redirect the pre-commit hook towards a different file (i.e. add --hook-config=--path-to-file=RANDOM.md to the args), then I can get the desired output in README.md and the console output as shown in the image above in RANDOM.md. This leads me to believe there is something happening in the handoff or a double-write operation causing the conflict here.

Final Solution

I realized that I can refactor my README.md and .terraform-docs.yml files to no longer use the custom comment template that pre-commit-terraform expects. Setting different comment strings in these two files means that pre-commit-terraform will no longer write the changes and instead terraform-docs will handle writing the output per it's config file.

In summary, if you are converting from a standard use of this hook and want to now use terraform-docs config file feature, change your comment strings in your target markdown file to anything else (for example, back to the default <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS -->)

# DO NOT USE if you want to specify a config file with an "output" block
<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

Hope this helps!

[UkklyDukkling]

As an aside, I think the greatest driver towards my use of a config file instead of cmd line arguments was the ability to fully customize the generated content. I can re-order the standard sections, add static text wherever I want, insert other files' contents, and (best of all) I am adding an auto-generated code block that users will be able to copy/paste into their projects to consume the terraform module for ease-of-use.

That code block will be automagically updated for any terraform file changes instead of having to manually maintain the doc! (I'm going to be building sooo many modules and don't want to maintain that 😄 )

[MaxymVlasov]

@drAlberT @UkklyDukkling can you please point how you were able to replicate

- --hook-config=--create-file-if-not-exist=true

in your terraform-docs.yaml config?

And if you have idea how make - --hook-config=--add-to-existing-file=true working for inject mode using only native terraform-docs.yaml configs, let me know too.
(Btw, I don't think that hook currently able to work with replace mode, could be fixed after #179 implementation)

just in case,

• starting from https://github.com/antonbabenko/pre-commit-terraform/releases/tag/v1.92.2, output.file setting from .terraform-docs.yml config prioritized over --hook-config=--path-to-file=
• starting from https://github.com/antonbabenko/pre-commit-terraform/releases/tag/v1.93.0 <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS --> markers used by default (with under-the-hood replacement of old-one markers)

Which means that next settings, not more needed

- --hook-config=--path-to-file=
- --hook-config=--use-standard-markers=

And now we need to figure-out how to deal with

- --hook-config=--add-to-existing-file=true     # Boolean. true or false
- --hook-config=--create-file-if-not-exist=true # Boolean. true or false

[MaxymVlasov]

@drAlberT @UkklyDukkling can you please point how you were able to replicate

- --hook-config=--create-file-if-not-exist=true

in your terraform-docs.yaml config?

TL;DR: terraform-docs always generate section to file, no matter what, #715.

So we still need --hook-config=--add-to-existing-file= at least to disable addition of such sections. Defaults could be changed in v2.0, but I don't think that it worth it.

--hook-config=--create-file-if-not-exist= not supported by terraform-docs