terraform-docs · Varantha · Sep 16, 2023 · Sep 16, 2023 · Sep 16, 2023 · Sep 16, 2023
diff --git a/examples/.terraform-docs.yml b/examples/.terraform-docs.yml
@@ -19,6 +19,7 @@ footer-from: footer.md
 sections:
   show:
     - header
+    - examples
     - inputs
     - providers
     - modules
@@ -87,5 +88,5 @@ settings:
   indent: 4
   escape: false
   default: false
-  required: false
+  required: true
   type: true
diff --git a/examples/examples/exampleA/main.tf b/examples/examples/exampleA/main.tf
@@ -0,0 +1,17 @@
+module full-example{
+    source = "github.com/terraform-docs/terraform-docs//examples"
+
+    input_with_underscores = "input_any"
+    list-2 = [
+        "value_1",
+        "value_2"
+    ]
+    map-2 = {
+        "1" = "value"
+        "2" = "value_2"
+    }
+    number-2 = 2
+    string-2 = "2"
+    string_no_default = "string_value"
+    unquoted = test
+}
diff --git a/format/asciidoc_document_test.go b/format/asciidoc_document_test.go
@@ -106,6 +106,11 @@ func TestAsciidocDocument(t *testing.T) {
 		"OnlyDataSources": {
 			config: testutil.With(func(c *print.Config) { c.Sections.DataSources = true }),
 		},
+		"OnlyExamples": {
+			config: testutil.With(func(c *print.Config) {
+				c.Sections.Examples = true
+			}),
+		},
 		"OnlyHeader": {
 			config: testutil.With(func(c *print.Config) { c.Sections.Header = true }),
 		},

diff --git a/format/asciidoc_table_test.go b/format/asciidoc_table_test.go
@@ -106,6 +106,11 @@ func TestAsciidocTable(t *testing.T) {
 		"OnlyDataSources": {
 			config: testutil.With(func(c *print.Config) { c.Sections.DataSources = true }),
 		},
+		"OnlyExamples": {
+			config: testutil.With(func(c *print.Config) {
+				c.Sections.Examples = true
+			}),
+		},
 		"OnlyHeader": {
 			config: testutil.With(func(c *print.Config) { c.Sections.Header = true }),
 		},

diff --git a/format/generator.go b/format/generator.go
@@ -87,6 +87,13 @@ func withResources(resources string) generateFunc {
 	}
 }
 
+// withExamples specifies how the generator should add Examples.
+func withExamples(examples string) generateFunc {
+	return func(g *generator) {
+		g.examples = examples
+	}
+}
+
 // withModule specifies how the generator should add Resources.
 func withModule(module *terraform.Module) generateFunc {
 	return func(g *generator) {
@@ -122,6 +129,7 @@ type generator struct {
 	providers    string
 	requirements string
 	resources    string
+	examples     string
 
 	config *print.Config
 	module *terraform.Module
@@ -177,6 +185,9 @@ func (g *generator) Requirements() string { return g.requirements }
 // Resources returns generted requirements section based on the underlying format.
 func (g *generator) Resources() string { return g.resources }
 
+// Module returns generated example section based on the underlying format.
+func (g *generator) Examples() string { return g.examples }
+
 // Module returns generted requirements section based on the underlying format.
 func (g *generator) Module() *terraform.Module { return g.module }
 
@@ -253,6 +264,7 @@ func (g *generator) forEach(render func(string) (string, error)) error {
 		"providers":    withProviders,
 		"requirements": withRequirements,
 		"resources":    withResources,
+		"examples":     withExamples,
 	}
 	for name, callback := range mappings {
 		result, err := render(name)

diff --git a/format/json_test.go b/format/json_test.go
@@ -62,6 +62,11 @@ func TestJson(t *testing.T) {
 		"OnlyDataSources": {
 			config: testutil.With(func(c *print.Config) { c.Sections.DataSources = true }),
 		},
+		"OnlyExamples": {
+			config: testutil.With(func(c *print.Config) {
+				c.Sections.Examples = true
+			}),
+		},
 		"OnlyHeader": {
 			config: testutil.With(func(c *print.Config) { c.Sections.Header = true }),
 		},

diff --git a/format/markdown_document_test.go b/format/markdown_document_test.go
@@ -143,6 +143,11 @@ func TestMarkdownDocument(t *testing.T) {
 		"OnlyDataSources": {
 			config: testutil.With(func(c *print.Config) { c.Sections.DataSources = true }),
 		},
+		"OnlyExamples": {
+			config: testutil.With(func(c *print.Config) {
+				c.Sections.Examples = true
+			}),
+		},
 		"OnlyHeader": {
 			config: testutil.With(func(c *print.Config) { c.Sections.Header = true }),
 		},

diff --git a/format/markdown_table_test.go b/format/markdown_table_test.go
@@ -51,7 +51,6 @@ func TestMarkdownTable(t *testing.T) {
 				c.HeaderFrom = "bad.tf"
 			}),
 		},
-
 		// Settings
 		"WithRequired": {
 			config: testutil.WithSections(
@@ -143,6 +142,11 @@ func TestMarkdownTable(t *testing.T) {
 		"OnlyDataSources": {
 			config: testutil.With(func(c *print.Config) { c.Sections.DataSources = true }),
 		},
+		"OnlyExamples": {
+			config: testutil.With(func(c *print.Config) {
+				c.Sections.Examples = true
+			}),
+		},
 		"OnlyHeader": {
 			config: testutil.With(func(c *print.Config) { c.Sections.Header = true }),
 		},

diff --git a/format/templates/asciidoc_document.tmpl b/format/templates/asciidoc_document.tmpl
@@ -1,4 +1,5 @@
 {{- template "header" . -}}
+{{- template "examples" . -}}
 {{- template "requirements" . -}}
 {{- template "providers" . -}}
 {{- template "modules" . -}}

diff --git a/format/templates/asciidoc_document_examples.tmpl b/format/templates/asciidoc_document_examples.tmpl
@@ -0,0 +1,22 @@
+{{- if .Config.Sections.Examples -}}
+    {{- if not .Module.Examples -}}
+        {{- if not .Config.Settings.HideEmpty -}}
+            {{- indent 0 "=" }} Examples
+
+            No examples.
+        {{ end }}
+    {{ else }}
+        {{- indent 0 "=" }} Examples 
+
+        {{$hideTitles := .Config.Examples.HideTitles}} 
+        {{- range .Module.Examples }}
+            {{- if not $hideTitles }}
+                {{ indent 1 "=" }} {{ .Name }}
+            {{- end }}
+            ```hcl
+            {{ .Content }}
+            ```
+
+        {{ end }}
+    {{ end }}
+{{ end -}}
diff --git a/format/templates/asciidoc_table.tmpl b/format/templates/asciidoc_table.tmpl
@@ -1,4 +1,5 @@
 {{- template "header" . -}}
+{{- template "examples" . -}}
 {{- template "requirements" . -}}
 {{- template "providers" . -}}
 {{- template "modules" . -}}

diff --git a/format/templates/asciidoc_table_examples.tmpl b/format/templates/asciidoc_table_examples.tmpl
@@ -0,0 +1,22 @@
+{{- if .Config.Sections.Examples -}}
+    {{- if not .Module.Examples -}}
+        {{- if not .Config.Settings.HideEmpty -}}
+            {{- indent 0 "=" }} Examples
+
+            No examples.
+        {{ end }}
+    {{ else }}
+        {{- indent 0 "=" }} Examples 
+
+        {{$hideTitles := .Config.Examples.HideTitles}} 
+        {{- range .Module.Examples }}
+            {{- if not $hideTitles }}
+                {{ indent 1 "=" }} {{ .Name }}
+            {{- end }}
+            ```hcl
+            {{ .Content }}
+            ```
+
+        {{ end }}
+    {{ end }}
+{{ end -}}
diff --git a/format/templates/markdown_document.tmpl b/format/templates/markdown_document.tmpl
@@ -1,4 +1,5 @@
 {{- template "header" . -}}
+{{- template "examples" . -}}
 {{- template "requirements" . -}}
 {{- template "providers" . -}}
 {{- template "modules" . -}}

diff --git a/format/templates/markdown_document_examples.tmpl b/format/templates/markdown_document_examples.tmpl
@@ -0,0 +1,23 @@
+{{- if .Config.Sections.Examples -}}
+    {{- if not .Module.Examples -}}
+        {{- if not .Config.Settings.HideEmpty -}}
+            {{- indent 0 "#" }} Examples
+
+            No examples.
+        {{ end }}
+    {{ else }}
+        {{- indent 0 "#" }} Examples 
+
+        {{$hideTitles := .Config.Examples.HideTitles}} 
+        {{- range .Module.Examples }}
+            {{- if not $hideTitles }}
+                {{ indent 1 "#" }} {{ .Name }}
+
+            {{ end }}
+            ```hcl
+            {{ .Content }}
+            ```
+
+        {{ end }}
+    {{ end }}
+{{ end -}}
diff --git a/format/templates/markdown_table.tmpl b/format/templates/markdown_table.tmpl
@@ -1,4 +1,5 @@
 {{- template "header" . -}}
+{{- template "examples" . -}}
 {{- template "requirements" . -}}
 {{- template "providers" . -}}
 {{- template "modules" . -}}

diff --git a/format/templates/markdown_table_examples.tmpl b/format/templates/markdown_table_examples.tmpl
@@ -0,0 +1,23 @@
+{{- if .Config.Sections.Examples -}}
+    {{- if not .Module.Examples -}}
+        {{- if not .Config.Settings.HideEmpty -}}
+            {{- indent 0 "#" }} Examples
+
+            No examples.
+        {{ end }}
+    {{ else }}
+        {{- indent 0 "#" }} Examples 
+
+        {{$hideTitles := .Config.Examples.HideTitles}} 
+        {{- range .Module.Examples }}
+            {{- if not $hideTitles }}
+                {{ indent 1 "#" }} {{ .Name }}
+
+            {{ end }}
+            ```hcl
+            {{ .Content }}
+            ```
+
+        {{ end }}
+    {{ end }}
+{{ end -}}
diff --git a/format/templates/pretty.tmpl b/format/templates/pretty.tmpl
@@ -5,6 +5,17 @@
     {{- printf "\n\n" -}}
 {{ end -}}
 
+{{- if .Config.Sections.Examples -}}
+    {{- with .Module.Examples }}
+        {{- range . }}
+            {{- printf "example.%s" .Name | colorize "\033[36m" }}
+            {{ tostring .Content | colorize "\033[90m" }}
+            {{- printf "\n\n" -}}
+        {{ end -}}
+    {{ end -}}
+    {{- printf "\n" -}}
+{{ end -}}
+
 {{- if .Config.Sections.Requirements -}}
     {{- with .Module.Requirements }}
         {{- range . }}

diff --git a/format/testdata/asciidoc/document-Base.golden b/format/testdata/asciidoc/document-Base.golden
@@ -36,6 +36,29 @@ followed by another line of text.
 | Foo  | Foo description |
 | Bar  | Bar description |
 
+== Examples
+
+=== exampleA
+```hcl
+module full-example{
+    source = "github.com/terraform-docs/terraform-docs//examples"
+
+    input_with_underscores = "input_any"
+    list-2 = [
+        "value_1",
+        "value_2"
+    ]
+    map-2 = {
+        "1" = "value"
+        "2" = "value_2"
+    }
+    number-2 = 2
+    string-2 = "2"
+    string_no_default = "string_value"
+    unquoted = test
+}
+```
+
 == Requirements
 
 The following requirements are needed by this module:

diff --git a/format/testdata/asciidoc/document-IndentationOfFour.golden b/format/testdata/asciidoc/document-IndentationOfFour.golden
@@ -36,6 +36,29 @@ followed by another line of text.
 | Foo  | Foo description |
 | Bar  | Bar description |
 
+==== Examples
+
+===== exampleA
+```hcl
+module full-example{
+    source = "github.com/terraform-docs/terraform-docs//examples"
+
+    input_with_underscores = "input_any"
+    list-2 = [
+        "value_1",
+        "value_2"
+    ]
+    map-2 = {
+        "1" = "value"
+        "2" = "value_2"
+    }
+    number-2 = 2
+    string-2 = "2"
+    string_no_default = "string_value"
+    unquoted = test
+}
+```
+
 ==== Requirements
 
 The following requirements are needed by this module:

diff --git a/format/testdata/asciidoc/document-OnlyExamples.golden b/format/testdata/asciidoc/document-OnlyExamples.golden
@@ -0,0 +1,22 @@
+== Examples
+
+=== exampleA
+```hcl
+module full-example{
+    source = "github.com/terraform-docs/terraform-docs//examples"
+
+    input_with_underscores = "input_any"
+    list-2 = [
+        "value_1",
+        "value_2"
+    ]
+    map-2 = {
+        "1" = "value"
+        "2" = "value_2"
+    }
+    number-2 = 2
+    string-2 = "2"
+    string_no_default = "string_value"
+    unquoted = test
+}
+```
diff --git a/format/testdata/asciidoc/document-WithAnchor.golden b/format/testdata/asciidoc/document-WithAnchor.golden
@@ -36,6 +36,29 @@ followed by another line of text.
 | Foo  | Foo description |
 | Bar  | Bar description |
 
+== Examples
+
+=== exampleA
+```hcl
+module full-example{
+    source = "github.com/terraform-docs/terraform-docs//examples"
+
+    input_with_underscores = "input_any"
+    list-2 = [
+        "value_1",
+        "value_2"
+    ]
+    map-2 = {
+        "1" = "value"
+        "2" = "value_2"
+    }
+    number-2 = 2
+    string-2 = "2"
+    string_no_default = "string_value"
+    unquoted = test
+}
+```
+
 == Requirements
 
 The following requirements are needed by this module: