Include relative files into generated content

khos2ow · khos2ow · commit ea34bce326ed · 2021-05-13T12:53:25.000-04:00
Local relative files can be included automatically in the generated
content with `{{ include "..." }} function. This can be very useful
for:

- inject arbitrary markdown files in between sections
- automatically include example usage

````yaml
content: |-
  include any relative files

  {{ include "relative/path/to/file" }}

  or examples

  ```hcl
  {{ include "examples/foo/main.tf" }}
  ```
````

Signed-off-by: Khosrow Moossavi &lt;khos2ow@gmail.com&gt;
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -160,14 +160,14 @@ used for `FORMATTER_NAME`:
 use the plugin. For example, if plugin binary file is called `tfdocs-format-foo`,
 formatter name must be set to `foo`.
 
-## header-from
+## Header From
 
 Since `v0.10.0`
 
 Relative path to a file to extract header for the generated output from. Supported
 file formats are `.adoc`, `.md`, `.tf`, and `.txt`. Default value is `main.tf`.
 
-## footer-from
+## Footer From
 
 Since `v0.12.0`
 
@@ -211,7 +211,11 @@ Go template with following additional variables:
 - `{{ .Requirements }}`
 - `{{ .Resources }}`
 
-```yaml
+and
+
+- `{{ include "relative/path/to/file" }}`
+
+````yaml
 content: |-
   Any arbitrary text can be placed anywhere in the content
 
@@ -226,7 +230,17 @@ content: |-
   {{ .Outputs }}
 
   {{ .Inputs }}
-```
+
+  and include any relative files
+
+  {{ include "relative/path/to/file" }}
+
+  or examples
+
+  ```hcl
+  {{ include "examples/foo/main.tf" }}
+  ```
+````
 
 These variables are the generated output of individual sections in the selected
 formatter. For example `{{ .Inputs }}` is Markdown Table representation of _inputs_
diff --git a/docs/user-guide/how-to.md b/docs/user-guide/how-to.md
@@ -150,6 +150,46 @@ default file to attempt extraction from, you need to explicitly specify desired
 to extract content from with `--footer-from FILE` or corresponding `footer-from` in
 configuration file.
 
+## Include Examples
+
+Since `v0.14.0`
+
+Example can be automatically included into README by using `content` in configuration
+file. There are [multiple variables and function] available in `content`. As an example:
+
+````bash
+$ tree
+.
+├── examples
+│   ├── example-1
+│   │   ├── main.tf
+│   └── example-2
+│       └── main.tf
+├── ...
+├── main.tf
+├── variables.tf
+├── ...
+└── .terraform-docs.yml
+````
+
+and
+
+````yaml
+# .terraform-docs.yml
+content: |-
+  {{ .Header }}
+
+  ## Example
+
+  ```hcl
+  {{ file "example-1/main.tf" }}
+  ```
+
+  {{ .Inputs }}
+
+  {{ .Outputs }}
+````
+
 ## Insert Output To File
 
 Since `v0.12.0`
diff --git a/examples/.terraform-docs.yml b/examples/.terraform-docs.yml
@@ -24,6 +24,12 @@ sections:
 #
 #   and even in between sections
 #
+#   ## Examples
+#
+#   ```hcl
+#   {{ include "relative/path/to/main.tf" }}
+#   ```
+#
 #   {{ .Providers }}
 #
 #   and they don't even need to be in the default order
diff --git a/internal/cli/run.go b/internal/cli/run.go
@@ -149,6 +149,7 @@ func RunEFunc(config *Config) func(*cobra.Command, []string) error {
 		if err != nil {
 			return err
 		}
+		generator.Path(config.moduleRoot)
 
 		content, err := generator.ExecuteTemplate(config.Content)
 		if err != nil {
diff --git a/internal/print/generator.go b/internal/print/generator.go
@@ -12,6 +12,8 @@ package print
 
 import (
 	"bytes"
+	"os"
+	"path/filepath"
 	"text/template"
 )
 
@@ -106,6 +108,7 @@ type Generator struct {
 	Requirements string
 	Resources    string
 
+	path      string // module's path
 	content   string // all the content combined
 	formatter string // name of the formatter
 }
@@ -125,6 +128,11 @@ func NewGenerator(name string, fns ...GenerateFunc) *Generator {
 	return g
 }
 
+// Path of module's directory.
+func (g *Generator) Path(root string) {
+	g.path = root
+}
+
 // ExecuteTemplate applies the template with Generator known items. If template
 // is empty Generator.content is returned as is. If template is not empty this
 // still returns Generator.content for incompatible formatters.
@@ -140,6 +148,15 @@ func (g *Generator) ExecuteTemplate(contentTmpl string) (string, error) {
 	var buf bytes.Buffer
 
 	tmpl := template.New("content")
+	tmpl.Funcs(template.FuncMap{
+		"include": func(s string) string {
+			content, err := os.ReadFile(filepath.Join(g.path, s))
+			if err != nil {
+				panic(err)
+			}
+			return string(content)
+		},
+	})
 	template.Must(tmpl.Parse(contentTmpl))
 
 	if err := tmpl.ExecuteTemplate(&buf, "content", g); err != nil {
diff --git a/internal/print/generator_test.go b/internal/print/generator_test.go
@@ -107,6 +107,20 @@ func TestExecuteTemplate(t *testing.T) {
 			expected: "",
 			wantErr:  true,
 		},
+		"Compatible with template include file": {
+			name:     "markdown table",
+			content:  "this is the header\nthis is the footer",
+			template: "{{ include \"testdata/sample-file.txt\" }}",
+			expected: "Sample file to be included.\n",
+			wantErr:  false,
+		},
+		"Compatible with template include unknown file": {
+			name:     "markdown table",
+			content:  "this is the header\nthis is the footer",
+			template: "{{ include \"file-not-found\" }}",
+			expected: "",
+			wantErr:  true,
+		},
 		"Incompatible without template": {
 			name:     "yaml",
 			content:  "header: \"this is the header\"\nfooter: \"this is the footer\"",
diff --git a/internal/print/testdata/sample-file.txt b/internal/print/testdata/sample-file.txt
@@ -0,0 +1 @@
+Sample file to be included.

Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,12 @@ sections:`
`24`	`24`	`#`
`25`	`25`	`# and even in between sections`
`26`	`26`	`#`
	`27`	`+# ## Examples`
	`28`	`+#`
	`29`	+# ```hcl
	`30`	`+# {{ include "relative/path/to/main.tf" }}`
	`31`	+# ```
	`32`	`+#`
`27`	`33`	`# {{ .Providers }}`
`28`	`34`	`#`
`29`	`35`	`# and they don't even need to be in the default order`
Original file line number	Diff line number	Diff line change
`@@ -149,6 +149,7 @@ func RunEFunc(config Config) func(cobra.Command, []string) error {`
`149`	`149`	`if err != nil {`
`150`	`150`	`return err`
`151`	`151`	`}`
	`152`	`+ generator.Path(config.moduleRoot)`
`152`	`153`
`153`	`154`	`content, err := generator.ExecuteTemplate(config.Content)`
`154`	`155`	`if err != nil {`