How to run terraform-docs for code inside a sub folder

[maulik-vimond]

I am trying to run terraform-docs hook for the terraform configuration inside a subfolder called "terraform". When I run pre-commit run terraform_docs -a no documentation is generated. The output says "Passed" for terraform docs.

But if I run terraform-docs manually it works using terraform-docs md ./terraform

Here is my config file:

repos:
  - repo: https://github.com/talos-systems/conform
    rev: v0.1.0-alpha.20
    hooks:
      - id: conform
  - repo: git://github.com/antonbabenko/pre-commit-terraform
    rev: v1.47.0
    hooks:
    - id: terraform_fmt
    - id: terraform_docs
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
    - id: end-of-file-fixer

I am using,
pre-commit=2.10.1
terraform-docs=0.11.2
pre-commit-terraform=1.47.0

[maulik-vimond]

I found the problem,

pre-commit-terraform/terraform_docs.sh

Line 128 in d303bff

terraform-docs md $args ./ > "$tmp_file"

And I have found the workaround using terraform_docs_replace and specify a destination file.

EDIT: I have updated the code to point to the correct version

[sajidk1]

I found the problem, https://github.com/antonbabenko/pre-commit-terraform/blob/master/terraform_docs.sh#L128

And I have found the workaround using terraform_docs_replace and specify a destination file.

Can you share the workaround please? We also have terraform in sub folders

[maulik-vimond]

@sajid-khan-js We simply switched to using the following that will create TFDOC.md file for each module (including nested modules).

- id: terraform_docs_replace
      args: ['--sort-by-required', '--dest=TFDOC.md']

[sajidk1]

Thanks @maulik-vimond.

terraform_docs_replace does not fit our needs since we use the inline hooks (we have user generated docs also in the readme).

Strangely, switching to terraform_docs_without_aggregate_type_defaults works! I have no idea why, it's the exact same script/hook: #150

I've only tested locally, so not sure if it's my setup. Once I get this added to our CI environment I can confirm the odd result.

[maulik-vimond]

@sajid-khan-js yes of course. We came to a compromise of having a separate doc for terraform.

I think terraform_docs_without_aggregate_type_defaults works because of the condition (using awk?) and hitting this line:

pre-commit-terraform/terraform_docs.sh

Line 139 in fa3859e

terraform-docs md $args "$tmp_file_docs_tf" > "$tmp_file"

[brettcurtis]

Is this still not working? I can't figure out how to get a single subfolder to work. Ideally, I want two "global" & "regional" -

.
├── README.md
├── global
│   ├── backend.tf -> ../shared/backend.tf
│   ├── main.tf
│   ├── outputs.tf
│   ├── plan.out
│   ├── tfvars
│   │   ├── acc.tfvars
│   │   ├── exp.tfvars
│   │   ├── prod.tfvars
│   │   ├── sb.tfvars
│   │   └── uat.tfvars
│   └── variables.tf
├── plan.out
├── regional
│   ├── backend.tf -> ../shared/backend.tf
│   ├── main.tf
│   ├── outputs.tf
│   ├── plan.out
│   ├── tfvars
│   │   ├── europe-west1-acc.tfvars
│   │   ├── europe-west1-exp.tfvars
│   │   ├── europe-west1-prod.tfvars
│   │   ├── europe-west1-sb.tfvars
│   │   ├── europe-west1-uat.tfvars
│   │   ├── europe-west4-exp.tfvars
│   │   ├── europe-west4-prod.tfvars
│   │   └── europe-west4-sb.tfvars
│   └── variables.tf
└── shared
    └── backend.tf

pre-commit 2.13.0
terraform-docs version v0.14.1 linux/amd64

[ilyagorban-codefresh]

I still have the same issue (empty markdown file in subfolders) with:
pre-commit 2.14.0
terraform-docs version v0.15.0 darwin/amd64

The workaround below does not work for me

@sajid-khan-js We simply switched to using the following that will create TFDOC.md file for each module (including nested modules).

- id: terraform_docs_replace
      args: ['--sort-by-required', '--dest=TFDOC.md']

Workaround that worked for me (although it is not sorts):

pre-commit autoupdate
pre-commit uninstall
pre-commit install

and removal of '--sort-by-required'

[github-actions]

This issue has been automatically marked as stale because it has been open 30 days
with no activity. Remove stale label or comment or this issue will be closed in 10 days

[MaxymVlasov]

If I rightly understand this issue, here is few things that should be done:

1. Create docs from scratch if file (default - README.md) does not exist yet (flag --create-file-if-not-exist=false)

2. Add markers to doc, if markers not yet added (flag --add-to-exiting-file=false)

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

3. And, relate to Allow to specify filename to update (default, README.md) (flag --path-to-file=README.md) from Add hook to generate documentation using terraform-docs #7

[MaxymVlasov]

Hi @maulik-vimond @brettcurtis @sajid-khan-js @ilyagorban-codefresh
You can test #245 to confirm that it works fine for you.

[brettcurtis]

@MaxymVlasov - thanks for the update. I'm not sure that PR is addressing the issue I have of being able to populate the README with values from multiple terraform subfolders?

[MaxymVlasov]

Hmm, it's an interesting issue.
It is not easy to implement, during that need to understand what is exactly is needed and then change perl logic here. At least, I do not see regular expressions :D

@brettcurtis can you please create new feature request for that and provide details like:

1. Code structure
2. Some examples of README that you'd like to have.
3. Do you need to generate README in root for all subfolders, or you'd like to populate a few README's, eg:

├── dev
│   ├── README.md
│   └── dirs...
├── prod
│   ├── README.md
│   └── dirs...

4. Why you choose that documentation flow. What it helps to achive?
5. All other info that you think will be helpful

[maulik-vimond]

Yes I agree with @brettcurtis. The core issue is that the current version checks for files in the current folder only. In our project we had all our terraform configuration inside a sub-folder. If you have multiple sub-folders as in your last example, that also needs to be addressed in this case.

[MaxymVlasov]

@maulik-vimond What do you mean by "current folder"?
terrafrom_docs hook check all folders where .tf files changed (or exist if you run pre-commit run -a) and update doc between docs hook markers

#245 introduce the ability to change the name and location of docfile, so after release, you'll be able to use constructions like:

.
├── TFDOC.md
├── somefolder
│   ├── main.tf
│   ├── vars.tf

that populates info about .tf files in somefolder to ../TFDOC.md

If you have multiple sub-folders as in your last example

Well, I still need more details about this flow, as I mentioned above

[maulik-vimond]

@MaxymVlasov By current folder, I meant the root folder where you have defined the pre-commit config file.

I tested the terraform_docs hook using your PR and I can confirm that it was able to pick up the terraform files in a sub-folder as well as in the root folder.

[brettcurtis]

I've tested this too and in my case I have no .tf file in my root but .tf files in multiple subfolders like so:

README.md
├── infra
│   ├── *.tf
├── app
│   ├── *.tf

If I do this:

  - repo: git://github.com/antonbabenko/pre-commit-terraform
    rev: c7835fe7151e844416d2fb42a729a18e4043de27
    hooks:
      - id: terraform_docs
        args:
          - --hook-config=--add-to-exiting-file=true # Boolean. true or false

my root level README.md only populates from my infra folder and not my app folder. I would expect my root level README.md to populate with both I guess.

That being said this works and populates a README.md in each folder:

  - repo: git://github.com/antonbabenko/pre-commit-terraform
    rev: c7835fe7151e844416d2fb42a729a18e4043de27
    hooks:
      - id: terraform_docs
        args:
          - --hook-config=--path-to-file=README.md # Valid UNIX path. I.e. ../TFDOC.md or docs/README.md etc.
          - --hook-config=--add-to-exiting-file=true # Boolean. true or false
          - --hook-config=--create-file-if-not-exist=true # Boolean. true or false

This is nice and what I can do is link from my root README.md to these individual folder README.md - Thanks for working on this!