Skip to content

Commit 6777364

Browse files
khos2owkhos2ow
committed
Customize content with individual sections output
Generated content can be customized further away with `content` in configuration. If the `content` is empty the default orders of section is used. `content` is a Go template with following additional variables: - `{{ .Header }}` - `{{ .Footer }}` - `{{ .Inputs }}` - `{{ .Modules }}` - `{{ .Outputs }}` - `{{ .Providers }}` - `{{ .Requirements }}` - `{{ .Resources }}` ```yaml content: |- Any arbitrary text can be placed anywhere in the content {{ .Header }} and even in between sections {{ .Providers }} and they don't even need to be in the default order {{ .Outputs }} {{ .Inputs }} ``` These variables are the generated output of individual sections in the selected formatter. For example `{{ .Inputs }}` is Markdown Table representation of inputs when formatter is set to `markdown table` and AsciiDoc Document representation when formatter is set to `asciidoc document` and so on. Compatible formats for customized content are: - `asciidoc document` - `asciidoc table` - `markdown document` - `markdown table` Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
1 parent 4fd410b commit 6777364

File tree

71 files changed

+1425
-723
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+1425
-723
lines changed

‎docs/user-guide/configuration.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ sections:
7272
hide-all: false # deprecated in v0.13.0
7373
show-all: true # deprecated in v0.13.0
7474

75+
content: ""
76+
7577
output:
7678
file: ""
7779
mode: inject
@@ -192,6 +194,76 @@ The following options are supported and can be used for `sections.show` and
192194
**Note:** As of `v0.13.0`, `sections.hide-all` and `sections.show-all` are deprecated
193195
and removed in favor of explicit use of `sections.hide` and `sections.show`.
194196

197+
## Content
198+
199+
Since `v0.14.0`
200+
201+
Generated content can be customized further away with `content` in configuration.
202+
If the `content` is empty the default orders of section is used. `content` is a
203+
Go template with following additional variables:
204+
205+
- `{{ .Header }}`
206+
- `{{ .Footer }}`
207+
- `{{ .Inputs }}`
208+
- `{{ .Modules }}`
209+
- `{{ .Outputs }}`
210+
- `{{ .Providers }}`
211+
- `{{ .Requirements }}`
212+
- `{{ .Resources }}`
213+
214+
```yaml
215+
content: |-
216+
Any arbitrary text can be placed anywhere in the content
217+
218+
{{ .Header }}
219+
220+
and even in between sections
221+
222+
{{ .Providers }}
223+
224+
and they don't even need to be in the default order
225+
226+
{{ .Outputs }}
227+
228+
{{ .Inputs }}
229+
```
230+
231+
These variables are the generated output of individual sections in the selected
232+
formatter. For example `{{ .Inputs }}` is Markdown Table representation of _inputs_
233+
when formatter is set to `markdown table` and AsciiDoc Document representation
234+
when formatter is set to `asciidoc document` and so on.
235+
236+
Compatible formats for customized content are:
237+
238+
- `asciidoc document`
239+
- `asciidoc table`
240+
- `markdown document`
241+
- `markdown table`
242+
243+
**Note:** Sections visibility (i.e. `sections.show` and `sections.hide`) takes
244+
precedence over the `content`. In the following example although `{{ .Providers }}`
245+
is used it won't be rendered because `providers` is not set to be shown in
246+
`sections.show`.
247+
248+
```yaml
249+
sections:
250+
show:
251+
- header
252+
- inputs
253+
- outputs
254+
255+
content: |-
256+
{{ .Header }}
257+
258+
Some more information can go here.
259+
260+
{{ .Providers }}
261+
262+
{{ .Inputs }}
263+
264+
{{ .Outputs }}
265+
```
266+
195267
## Output
196268

197269
Since `v0.12.0`

‎examples/.terraform-docs.yml

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
1-
# # terraform-docs version constraints for execution
2-
# # more information: https://terraform-docs.io/user-guide/configuration/#version
1+
# # see: https://terraform-docs.io/user-guide/configuration/#version
32
# version: ">= 0.10, < 0.12"
43

4+
# see: https://terraform-docs.io/user-guide/configuration/#formatters
55
formatter: markdown table
66

77
header-from: doc.txt
88
footer-from: footer.md
99

10+
# see: https://terraform-docs.io/user-guide/configuration/#sections
1011
sections:
1112
show:
1213
- header
@@ -15,6 +16,23 @@ sections:
1516
- modules
1617
- footer
1718

19+
# # see: https://terraform-docs.io/user-guide/configuration/#content
20+
# content: |-
21+
# Any arbitrary text can be placed anywhere in the content
22+
#
23+
# {{ .Header }}
24+
#
25+
# and even in between sections
26+
#
27+
# {{ .Providers }}
28+
#
29+
# and they don't even need to be in the default order
30+
#
31+
# {{ .Outputs }}
32+
#
33+
# {{ .Inputs }}
34+
35+
# # see: https://terraform-docs.io/user-guide/configuration/#output
1836
# output:
1937
# file: README.md
2038
# mode: inject
@@ -23,12 +41,13 @@ sections:
2341
# The template can be customized with aribitrary markdown content.
2442
# For example this can be shown before the actual content generated
2543
# by formatters.
26-
44+
#
2745
# {{ .Content }}
28-
46+
#
2947
# You can also show something after it!
3048
# <!-- END_TF_DOCS -->
3149

50+
# see: https://terraform-docs.io/user-guide/configuration/#sort
3251
sort:
3352
enabled: true
3453
by: required

‎go.mod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ require (
1313
github.com/spf13/pflag v1.0.5
1414
github.com/spf13/viper v1.7.1
1515
github.com/stretchr/testify v1.7.0
16-
github.com/terraform-docs/plugin-sdk v0.3.0
16+
github.com/terraform-docs/plugin-sdk v0.3.1-0.20210512170044-49b620c0a2da
1717
github.com/terraform-docs/terraform-config-inspect v0.0.0-20210318143659-b932ca5358a6
1818
gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b
1919
honnef.co/go/tools v0.1.2

‎go.sum

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -237,8 +237,8 @@ github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5Cc
237237
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
238238
github.com/subosito/gotenv v1.2.0 h1:Slr1R9HxAlEKefgq5jn9U+DnETlIUa6HfgEzj0g5d7s=
239239
github.com/subosito/gotenv v1.2.0/go.mod h1:N0PQaV/YGNqwC0u51sEeR/aUtSLEXKX9iv69rRypqCw=
240-
github.com/terraform-docs/plugin-sdk v0.3.0 h1:+2NxYMXhyDJ4fQHW5UYfDlF5Dpip2xMo7STSvBy+zok=
241-
github.com/terraform-docs/plugin-sdk v0.3.0/go.mod h1:3G+0nZTeaMF1c5CZh8cOEYeNq0kUL6+DlQOVcxK7eCQ=
240+
github.com/terraform-docs/plugin-sdk v0.3.1-0.20210512170044-49b620c0a2da h1:WJXjngYRi9rtvzFFKjYuiWpax9R6tEiAA9givVSA4tw=
241+
github.com/terraform-docs/plugin-sdk v0.3.1-0.20210512170044-49b620c0a2da/go.mod h1:3G+0nZTeaMF1c5CZh8cOEYeNq0kUL6+DlQOVcxK7eCQ=
242242
github.com/terraform-docs/terraform-config-inspect v0.0.0-20210318143659-b932ca5358a6 h1:chOGKLaX5wNawU8rcF6HFJL+N5uU1Km8SiUQ/Ggwu2I=
243243
github.com/terraform-docs/terraform-config-inspect v0.0.0-20210318143659-b932ca5358a6/go.mod h1:GtanFwTsRRXScYHOMb5h4K18XQBFeS2tXat9/LrPtPc=
244244
github.com/tmc/grpc-websocket-proxy v0.0.0-20190109142713-0ad062ec5ee5/go.mod h1:ncp9v5uamzpCO7NfCPTXjqaC+bZgJeR0sMTm6dMHP7U=

‎internal/cli/config.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ type Config struct {
5656
Version string `mapstructure:"version"`
5757
HeaderFrom string `mapstructure:"header-from"`
5858
FooterFrom string `mapstructure:"footer-from"`
59+
Content string `mapstructure:"content"`
5960
Sections sections `mapstructure:"sections"`
6061
Output output `mapstructure:"output"`
6162
OutputValues outputvalues `mapstructure:"output-values"`
@@ -74,6 +75,7 @@ func DefaultConfig() *Config {
7475
Version: "",
7576
HeaderFrom: "main.tf",
7677
FooterFrom: "",
78+
Content: "",
7779
Sections: defaultSections(),
7880
Output: defaultOutput(),
7981
OutputValues: defaultOutputValues(),

‎internal/cli/run.go

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ func RunEFunc(config *Config) func(*cobra.Command, []string) error {
123123
return err
124124
}
125125

126-
printer, err := format.Factory(config.Formatter, settings)
126+
formatter, err := format.Factory(config.Formatter, settings)
127127
if err != nil {
128128
plugins, perr := plugin.Discover()
129129
if perr != nil {
@@ -145,10 +145,16 @@ func RunEFunc(config *Config) func(*cobra.Command, []string) error {
145145
return writeContent(config, content)
146146
}
147147

148-
content, err := printer.Print(module, settings)
148+
generator, err := formatter.Generate(module)
149149
if err != nil {
150150
return err
151151
}
152+
153+
content, err := generator.ExecuteTemplate(config.Content)
154+
if err != nil {
155+
return err
156+
}
157+
152158
return writeContent(config, content)
153159
}
154160
}

‎internal/format/asciidoc_document.go

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,29 +11,30 @@ the root directory of this source tree.
1111
package format
1212

1313
import (
14-
_ "embed" //nolint
14+
"embed"
1515
gotemplate "text/template"
1616

1717
"github.com/terraform-docs/terraform-docs/internal/print"
1818
"github.com/terraform-docs/terraform-docs/internal/template"
1919
"github.com/terraform-docs/terraform-docs/internal/terraform"
2020
)
2121

22-
//go:embed templates/asciidoc_document.tmpl
23-
var asciidocDocumentTpl []byte
22+
//go:embed templates/asciidoc_document*.tmpl
23+
var asciidocsDocumentFS embed.FS
2424

2525
// AsciidocDocument represents AsciiDoc Document format.
2626
type AsciidocDocument struct {
2727
template *template.Template
28+
settings *print.Settings
2829
}
2930

3031
// NewAsciidocDocument returns new instance of AsciidocDocument.
3132
func NewAsciidocDocument(settings *print.Settings) print.Engine {
33+
items := readTemplateItems(asciidocsDocumentFS, "asciidoc_document")
34+
3235
settings.EscapeCharacters = false
33-
tt := template.New(settings, &template.Item{
34-
Name: "document",
35-
Text: string(asciidocDocumentTpl),
36-
})
36+
37+
tt := template.New(settings, items...)
3738
tt.CustomFunc(gotemplate.FuncMap{
3839
"type": func(t string) string {
3940
result, extraline := printFencedAsciidocCodeBlock(t, "hcl")
@@ -58,16 +59,28 @@ func NewAsciidocDocument(settings *print.Settings) print.Engine {
5859
})
5960
return &AsciidocDocument{
6061
template: tt,
62+
settings: settings,
6163
}
6264
}
6365

64-
// Print a Terraform module as AsciiDoc document.
65-
func (d *AsciidocDocument) Print(module *terraform.Module, settings *print.Settings) (string, error) {
66-
rendered, err := d.template.Render(module)
66+
// Generate a Terraform module as AsciiDoc document.
67+
func (d *AsciidocDocument) Generate(module *terraform.Module) (*print.Generator, error) {
68+
funcs := []print.GenerateFunc{}
69+
70+
err := print.ForEach(func(name string, fn print.GeneratorCallback) error {
71+
rendered, err := d.template.Render(name, module)
72+
if err != nil {
73+
return err
74+
}
75+
76+
funcs = append(funcs, fn(sanitize(rendered)))
77+
return nil
78+
})
6779
if err != nil {
68-
return "", err
80+
return nil, err
6981
}
70-
return sanitize(rendered), nil
82+
83+
return print.NewGenerator("asciidoc document", funcs...), nil
7184
}
7285

7386
func init() {

‎internal/format/asciidoc_document_test.go

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -178,8 +178,12 @@ func TestAsciidocDocument(t *testing.T) {
178178
module, err := testutil.GetModule(options)
179179
assert.Nil(err)
180180

181-
printer := NewAsciidocDocument(&tt.settings)
182-
actual, err := printer.Print(module, &tt.settings)
181+
formatter := NewAsciidocDocument(&tt.settings)
182+
183+
generator, err := formatter.Generate(module)
184+
assert.Nil(err)
185+
186+
actual, err := generator.ExecuteTemplate("")
183187

184188
assert.Nil(err)
185189
assert.Equal(expected, actual)

‎internal/format/asciidoc_table.go

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,29 +11,30 @@ the root directory of this source tree.
1111
package format
1212

1313
import (
14-
_ "embed" //nolint
14+
"embed"
1515
gotemplate "text/template"
1616

1717
"github.com/terraform-docs/terraform-docs/internal/print"
1818
"github.com/terraform-docs/terraform-docs/internal/template"
1919
"github.com/terraform-docs/terraform-docs/internal/terraform"
2020
)
2121

22-
//go:embed templates/asciidoc_table.tmpl
23-
var asciidocTableTpl []byte
22+
//go:embed templates/asciidoc_table*.tmpl
23+
var asciidocTableFS embed.FS
2424

2525
// AsciidocTable represents AsciiDoc Table format.
2626
type AsciidocTable struct {
2727
template *template.Template
28+
settings *print.Settings
2829
}
2930

3031
// NewAsciidocTable returns new instance of AsciidocTable.
3132
func NewAsciidocTable(settings *print.Settings) print.Engine {
33+
items := readTemplateItems(asciidocTableFS, "asciidoc_table")
34+
3235
settings.EscapeCharacters = false
33-
tt := template.New(settings, &template.Item{
34-
Name: "table",
35-
Text: string(asciidocTableTpl),
36-
})
36+
37+
tt := template.New(settings, items...)
3738
tt.CustomFunc(gotemplate.FuncMap{
3839
"type": func(t string) string {
3940
inputType, _ := printFencedCodeBlock(t, "")
@@ -49,16 +50,28 @@ func NewAsciidocTable(settings *print.Settings) print.Engine {
4950
})
5051
return &AsciidocTable{
5152
template: tt,
53+
settings: settings,
5254
}
5355
}
5456

55-
// Print a Terraform module as AsciiDoc tables.
56-
func (t *AsciidocTable) Print(module *terraform.Module, settings *print.Settings) (string, error) {
57-
rendered, err := t.template.Render(module)
57+
// Generate a Terraform module as AsciiDoc tables.
58+
func (t *AsciidocTable) Generate(module *terraform.Module) (*print.Generator, error) {
59+
funcs := []print.GenerateFunc{}
60+
61+
err := print.ForEach(func(name string, fn print.GeneratorCallback) error {
62+
rendered, err := t.template.Render(name, module)
63+
if err != nil {
64+
return err
65+
}
66+
67+
funcs = append(funcs, fn(sanitize(rendered)))
68+
return nil
69+
})
5870
if err != nil {
59-
return "", err
71+
return nil, err
6072
}
61-
return sanitize(rendered), nil
73+
74+
return print.NewGenerator("asciidoc table", funcs...), nil
6275
}
6376

6477
func init() {

‎internal/format/asciidoc_table_test.go

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -178,8 +178,12 @@ func TestAsciidocTable(t *testing.T) {
178178
module, err := testutil.GetModule(options)
179179
assert.Nil(err)
180180

181-
printer := NewAsciidocTable(&tt.settings)
182-
actual, err := printer.Print(module, &tt.settings)
181+
formatter := NewAsciidocTable(&tt.settings)
182+
183+
generator, err := formatter.Generate(module)
184+
assert.Nil(err)
185+
186+
actual, err := generator.ExecuteTemplate("")
183187

184188
assert.Nil(err)
185189
assert.Equal(expected, actual)

0 commit comments

Comments
 (0)