Anchors

[nitrocode]

Description of your changes

Fixes #408

I have:

• Read and followed terraform-docs' contribution process.
• All tests pass when I run make test.

How has this code been tested

Tested this locally and seems to work well with a single test case. Not all test cases pass. Waiting for more discussion.

Is there a way to regenerate the testdata or should I be updating that manually ?

[khos2ow]

I really like the idea @nitrocode and just wanted to give you a very early feedback.

[khos2ow]

Please hold off any major work on testing until #410 is done.

[nitrocode]

Ah I just added the --anchors switch and pushed it. I will hold off on making additional changes.

[khos2ow]

Thank you @nitrocode for starting working on this. This looks ok so far but it needs a bit of changing.

Also the commits in the PR should not contain a "merge commit" and they always need to be rebased. But it's completely up to you to have that in mind along the way, or just squash everything at the very end.

[nitrocode]

I'm having issues running test on the master branch.

$ make test
package github.com/nitrocode/terraform-docs/scripts/docs
	scripts/docs/generate.go:28:2: use of internal package github.com/terraform-docs/terraform-docs/internal/terraform not allowed

[khos2ow]

I'm wondering why it says package github.com/nitrocode/terraform-docs/scripts/docs? Technically you cannot access internal packages from github.com/terraform-docs/terraform-docs from github.com/nitrocode/terraform-docs.

Are you in GOPATH? If yes, $GOPATH/src/github.com/terraform-docs/terraform-docs should be your local cloned folder.

[nitrocode]

Thanks. I upgraded golang outside of homebrew and it's working now.

[nitrocode]

I was able to fix the commit history by basically deleting my branch and updating the files again... squashing commits before and after an in-between merge does not seem possible.

The asciidoc template doesn't look like it will work currently as anchors are different in asciidoc vs markdown.

Docs

• https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#links
• https://powerman.name/doc/asciidoc#anchor-1

[[anchor-1]]
Paragraph or block 1.

anchor:anchor-2[]
Paragraph or block 2.

<<anchor-1>>,
<<anchor-1,First anchor>>,
xref:anchor-2[],
xref:anchor-2[Second anchor].

I'll use the above model to update the asciidoc anchors.

[nitrocode]

@khos2ow could you review this again please ?

I'm unsure how to resolve the 2 errors below.

• codecov < 75%
• Generating docs throws an error and I see this on the master branch

  ✗ GOOS=linux GOARCH=amd64 go1.16 run ./scripts/docs/generate.go
  fork/exec /var/folders/2v/qj0vxglj3hsgcs5m_f4jprnw0000gn/T/go-build361031716/b001/exe/generate: exec format error
  

[khos2ow]

Couple of minor comments.

[khos2ow]

• codecov coverage dropped by 0.29% which can be ignored, but you also can add cases into templates_test.go#TestBuiltinFunc to cover newly added functions too.
• that's weird. what does make docs do, same error? and why do you have GOOS=linux? I thought you were using macos.

[nitrocode]

Thanks for reviewing. I'll jump on it today.

Yes, I'm on OSX and the issue was related to the go1.16 issue again...

Not to add too much scope creep to this PR but it would be nice to use an env var in the Makefile like GOBINARY=go which can be used in every target then if I need to overwrite it, I can simply do either

export GOBINARY=go1.16
make docs

or

GOBINARY=go1.16 make docs

[khos2ow]

That's a really good point, I'll add it in another PR! 👍

[khos2ow]

One last thing to do, please add anchor in:

• internal/cli/reader.go#L96
• docs/reference/config-file.md

Also please add a bit more information to commit message, as it will be shown in release note.

[khos2ow]

Thank you @nitrocode for all the efforts on this PR! 👍

[nitrocode]

I looked at all the tickets for the v0.12 project and it seems like this won't be released for some time. Would you be willing to cut a terraform-docs v0.12-beta1 release like they do with terraform ?

[khos2ow]

Yeah sure I'll cut a release soon, but also in the meantime you can use edge docker image, which is always HEAD of master. (although that might force a change in your workflow, but at least it's an option to immediately unblock you)

[nitrocode]

@khos2ow I'm playing with the new release now and it works great!

One thing. On the release notes, you put @ 9trocode instead of @nitrocode 😅

[khos2ow]

Interesting! The list of contributors are being extracted automatically, I should check that script to see why that happened! 😅

Updated release note, thanks for pointing this out and your contribution!