feat(terraform_docs): Add terraform-docs default markers support and describe how to migrate to them

[jonmcewen]

Put an x into the box if that apply:

• This PR introduces breaking change.
• This PR fixes a bug.
• This PR adds new functionality.
• This PR enhances existing functionality.

Description of your changes

Allow users to switch to the standard insertion markers used by terraform-docs, to enable CI jobs to check that docs have been updated.

How can we test changes

Based on this suggestion for testing hooks: #25 (comment)

Add the following to the pre-commit config:

- repo: local
  hooks:
  - id: terraform_docs
    name: terraform_docs
    entry: ./hooks/terraform_docs.sh
    args:
    - --hook-config=--path-to-file=README.md
    - --hook-config=--use-standard-markers=false
    - --hook-config=--create-file-if-not-exist=true
    - --hook-config=--add-to-existing-file=true
    language: system
    files: (\.tf)$

Add a new file outputs.tf:

output "my_output" {
  value       = aws_api_gateway_stage.blah.invoke_url
  description = "Description of the test output"
}

Stage the pre-commit config and the new outputs.tf file: git add .pre-commit-config.yaml outputs.tf

Using the existing README.md as a target:

• Test default behaviour has not changed:
  • pre-commit run -a should add the terraform docs between the existing markers
  • Delete the README. Then pre-commit run -a should create the file as normal
  • Delete the contents of the README. Then pre-commit run -a should add the terraform docs as normal
• Test the behaviour with "standard" markers
  • update the pre-commit config to set --hook-config=--use_standard_markers=true, and git add -u
  • Delete the README. Then pre-commit run -a should create the file as normal, but with different markers
  • git add README.md
  • update using terraform-docs: terraform-docs markdown --output-file=README.md .
  • there should be no changes made by terraform docs (git diff)
  • repeat this process in reverse (terraform-docs, then pre-commit)

For completeness, repeat the standard markers test for insertion between existing markers, and appending to an existing file with no markers (or check by code inspection).

[yermulnik]

While code in hooks/terraform_docs.sh looks decent per se, the PR looks to be a mess of superfluous files local to contributor 🤔

[jonmcewen]

While code in hooks/terraform_docs.sh looks decent per se, the PR looks to be a mess of superfluous files local to contributor 🤔

Yep, it's still WIP. Better now, but needs a little tidy up before review. I will hopefully finish this tomorrow

[jonmcewen]

@MaxymVlasov this is ready for review now. Thank you

[jonmcewen]

@yermulnik @MaxymVlasov thanks for the review. Please take another look

[yermulnik]

LGTM

[yermulnik]

Leaving this to @MaxymVlasov to also review and merge if he's fine with the change.

[MaxymVlasov]

Great, we will switch to tf-docs default markers in v2.0

[antonbabenko]

This PR is included in version 1.86.0 🎉

[jonmcewen]

Thanks for a great contribution experience everyone!

[jonmcewen]

I just found this: https://github.com/terraform-docs/terraform-docs/#pre-commit-hook

Can you offer any comparison between the two @antonbabenko ?

[MaxymVlasov]

Wow, didn't know that they have hooks.

As far as I see, https://github.com/terraform-docs/terraform-docs/#pre-commit-hook was added 2021-05-19 in 0.12.0, when terraform_docs hook exist from 2018-05-16 (1.7.0)

First of all, example in README

repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: "v0.17.0"
    hooks:
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md", "./mymodule/path"]

just not works, if, ofc, you want to add

      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md", "./mymodule/path"]
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md", "./mymodule/path2"]
     ....
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md", "./mymodule/pathN"]

And I don't get how to make work

repos:
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: "v0.17.0"
    hooks:
      - id: terraform-docs-go

with default .terraform-docs.yml (with formatter: "markdown") -

So far, I can say that terraform-docs/terraform-docs hooks just not work in real-case scenarios