Skip to content

Commit 465dd14

Browse files
khos2owkhos2ow
committed
Make terraform.Module available in content
Add one extra special variable the `content`: - `{{ .Module }}` As opposed to the other variables, which are generated sections based on a selected formatter, the `{{ .Module }}` variable is just a `struct` representing a Terraform module. It can be used to build highly complex and highly customized content: ```yaml content: |- ## Resources {{ range .Module.Resources }} - {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }}) {{- end }} ``` Signed-off-by: Khosrow Moossavi <[email protected]>
1 parent de684ce commit 465dd14

34 files changed

+461
-449
lines changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -312,11 +312,11 @@ func buildTerraformDocs(path string, tmpl string) (string, error) {
312312

313313
// // Note: if you don't intend to provide additional template for the generated
314314
// // content, or the target format doesn't provide templating (e.g. json, yaml,
315-
// // xml, or toml) you can use `Content()` function instead of `ExecuteTemplate()`.
315+
// // xml, or toml) you can use `Content()` function instead of `Render()`.
316316
// // `Content()` returns all the sections combined with predefined order.
317317
// return formatter.Content(), nil
318318

319-
return formatter.ExecuteTemplate(tmpl)
319+
return formatter.Render(tmpl)
320320
}
321321
```
322322

‎docs/user-guide/configuration/content.md‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,19 +29,27 @@ will be ignored for other formatters.
2929
- `{{ .Requirements }}`
3030
- `{{ .Resources }}`
3131

32-
and following functions:
33-
34-
- `{{ include "relative/path/to/file" }}`
35-
3632
These variables are the generated output of individual sections in the selected
3733
formatter. For example `{{ .Inputs }}` is Markdown Table representation of _inputs_
3834
when formatter is set to `markdown table`.
3935

4036
{{< alert type="info" >}}
41-
Sections visibility (i.e. `sections.show` and `sections.hide`) takes
42-
precedence over the `content`.
37+
Sections visibility (i.e. `sections.show` and `sections.hide`) takes precedence
38+
over the `content`.
4339
{{< /alert >}}
4440

41+
`content` also has the following function:
42+
43+
- `{{ include "relative/path/to/file" }}`
44+
45+
Additionally there's also one extra special variable avaialble to the `content`:
46+
47+
- `{{ .Module }}`
48+
49+
As opposed to the other variables mentioned above, which are generated sections
50+
based on a selected formatter, the `{{ .Module }}` variable is just a `struct`
51+
representing a [Terraform module].
52+
4553
## Options
4654

4755
Available options with their default values.
@@ -93,7 +101,7 @@ content: |-
93101
````
94102

95103
In the following example, although `{{ .Providers }}` is defined it won't be
96-
rendered because `providers` is not set to be shown in `sections.show`.
104+
rendered because `providers` is not set to be shown in `sections.show`:
97105

98106
```yaml
99107
sections:
@@ -113,3 +121,16 @@ content: |-
113121
114122
{{ .Outputs }}
115123
```
124+
125+
Building highly complex and highly customized content using `{{ .Module }}` struct:
126+
127+
```yaml
128+
content: |-
129+
## Resources
130+
131+
{{ range .Module.Resources }}
132+
- {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }})
133+
{{- end }}
134+
```
135+
136+
[Terraform module]: https://pkg.go.dev/github.com/terraform-docs/terraform-docs/terraform#Module

‎examples/.terraform-docs.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,11 @@ sections:
3232
#
3333
# and even in between sections
3434
#
35+
# ## Resources
36+
# {{ range .Module.Resources }}
37+
# - {{ .GetMode }}.{{ .Spec }} ({{ .Position.Filename }}#{{ .Position.Line }})
38+
# {{- end }}
39+
#
3540
# ## Examples
3641
#
3742
# ```hcl

‎format/asciidoc_document.go‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ var asciidocsDocumentFS embed.FS
2424

2525
// asciidocDocument represents AsciiDoc Document format.
2626
type asciidocDocument struct {
27-
*print.Generator
27+
*generator
2828

2929
config *print.Config
3030
template *template.Template
@@ -61,22 +61,24 @@ func NewAsciidocDocument(config *print.Config) Type {
6161
})
6262

6363
return &asciidocDocument{
64-
Generator: print.NewGenerator("json", config.ModuleRoot),
64+
generator: newGenerator(config, true),
6565
config: config,
6666
template: tt,
6767
}
6868
}
6969

7070
// Generate a Terraform module as AsciiDoc document.
7171
func (d *asciidocDocument) Generate(module *terraform.Module) error {
72-
err := d.Generator.ForEach(func(name string) (string, error) {
72+
err := d.generator.forEach(func(name string) (string, error) {
7373
rendered, err := d.template.Render(name, module)
7474
if err != nil {
7575
return "", err
7676
}
7777
return sanitize(rendered), nil
7878
})
7979

80+
d.generator.funcs(withModule(module))
81+
8082
return err
8183
}
8284

‎format/asciidoc_document_test.go‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -153,10 +153,7 @@ func TestAsciidocDocument(t *testing.T) {
153153
err = formatter.Generate(module)
154154
assert.Nil(err)
155155

156-
actual, err := formatter.ExecuteTemplate("")
157-
158-
assert.Nil(err)
159-
assert.Equal(expected, actual)
156+
assert.Equal(expected, formatter.Content())
160157
})
161158
}
162159
}

‎format/asciidoc_table.go‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ var asciidocTableFS embed.FS
2424

2525
// asciidocTable represents AsciiDoc Table format.
2626
type asciidocTable struct {
27-
*print.Generator
27+
*generator
2828

2929
config *print.Config
3030
template *template.Template
@@ -52,22 +52,24 @@ func NewAsciidocTable(config *print.Config) Type {
5252
})
5353

5454
return &asciidocTable{
55-
Generator: print.NewGenerator("json", config.ModuleRoot),
55+
generator: newGenerator(config, true),
5656
config: config,
5757
template: tt,
5858
}
5959
}
6060

6161
// Generate a Terraform module as AsciiDoc tables.
6262
func (t *asciidocTable) Generate(module *terraform.Module) error {
63-
err := t.Generator.ForEach(func(name string) (string, error) {
63+
err := t.generator.forEach(func(name string) (string, error) {
6464
rendered, err := t.template.Render(name, module)
6565
if err != nil {
6666
return "", err
6767
}
6868
return sanitize(rendered), nil
6969
})
7070

71+
t.generator.funcs(withModule(module))
72+
7173
return err
7274
}
7375

‎format/asciidoc_table_test.go‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -153,10 +153,7 @@ func TestAsciidocTable(t *testing.T) {
153153
err = formatter.Generate(module)
154154
assert.Nil(err)
155155

156-
actual, err := formatter.ExecuteTemplate("")
157-
158-
assert.Nil(err)
159-
assert.Equal(expected, actual)
156+
assert.Equal(expected, formatter.Content())
160157
})
161158
}
162159
}

‎format/doc.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,15 @@ the root directory of this source tree.
2828
// return err
2929
// }
3030
//
31-
// output, err := formatter.ExecuteTemplate("")
31+
// output, err := formatter.Render"")
3232
// if err != nil {
3333
// return err
3434
// }
3535
//
3636
// Note: if you don't intend to provide additional template for the generated
3737
// content, or the target format doesn't provide templating (e.g. json, yaml,
38-
// xml, or toml) you can use `Content()` function instead of `ExecuteTemplate()`.
39-
// `Content()` returns all the sections combined with predefined order.
38+
// xml, or toml) you can use `Content()` function instead of `Render)`. Note
39+
// that `Content()` returns all the sections combined with predefined order.
4040
//
4141
// output := formatter.Content()
4242
//

0 commit comments

Comments
 (0)