diff --git a/.editorconfig b/.editorconfig index f7ec36b..c1d75b2 100644 --- a/.editorconfig +++ b/.editorconfig @@ -16,6 +16,13 @@ insert_final_newline = true indent_style = tab indent_size = 4 +[*.md] +trim_trailing_whitespace = true + +[examples/doc.{adoc,md,tf,txt}] +trim_trailing_whitespace = false +insert_final_newline = false + [*.{golden,tmpl}] trim_trailing_whitespace = false insert_final_newline = false diff --git a/docs/reference/asciidoc-document.md b/docs/reference/asciidoc-document.md index b40793f..166702d 100644 --- a/docs/reference/asciidoc-document.md +++ b/docs/reference/asciidoc-document.md @@ -64,7 +64,7 @@ generates the following output: - list item 1 - list item 2 - Even inline **formatting** in _here_ is possible. + Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -87,7 +87,7 @@ generates the following output: } ``` - Here is some trailing text after code block, + Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/docs/reference/asciidoc-table.md b/docs/reference/asciidoc-table.md index 75ec3a3..c06a14e 100644 --- a/docs/reference/asciidoc-table.md +++ b/docs/reference/asciidoc-table.md @@ -64,7 +64,7 @@ generates the following output: - list item 1 - list item 2 - Even inline **formatting** in _here_ is possible. + Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -87,7 +87,7 @@ generates the following output: } ``` - Here is some trailing text after code block, + Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/docs/reference/markdown-document.md b/docs/reference/markdown-document.md index 24d3684..e2af9b2 100644 --- a/docs/reference/markdown-document.md +++ b/docs/reference/markdown-document.md @@ -65,7 +65,7 @@ generates the following output: - list item 1 - list item 2 - Even inline **formatting** in _here_ is possible. + Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -88,7 +88,7 @@ generates the following output: } ``` - Here is some trailing text after code block, + Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/docs/reference/markdown-table.md b/docs/reference/markdown-table.md index 22df215..414f374 100644 --- a/docs/reference/markdown-table.md +++ b/docs/reference/markdown-table.md @@ -65,7 +65,7 @@ generates the following output: - list item 1 - list item 2 - Even inline **formatting** in _here_ is possible. + Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -88,7 +88,7 @@ generates the following output: } ``` - Here is some trailing text after code block, + Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/docs/user-guide/how-to.md b/docs/user-guide/how-to.md index 57ee010..a21586c 100644 --- a/docs/user-guide/how-to.md +++ b/docs/user-guide/how-to.md @@ -27,8 +27,9 @@ terraform-docs --hide-all --show inputs --show outputs ... # hide all sections e ## Module Header Module header can be extracted from different sources. Default file to extract -header from is `main.tf`, otherwise you can specify the file with `--header-from FILE`. -Supported file formats to read header from are: +header from is `main.tf`, otherwise you can specify the file with `--header-from FILE` +or corresponding `header-from` in configuration file. Supported file formats to +read header from are: - `.adoc` - `.md` @@ -36,7 +37,7 @@ Supported file formats to read header from are: - `.txt` The whole file content is being extracted as module header when extracting from -`.adoc`, `.md` or `.txt`. But to extract header from `.tf` file you need to use +`.adoc`, `.md`, or `.txt`. But to extract header from `.tf` file you need to use following javascript, c or java like multi-line comment: ```tf @@ -57,6 +58,10 @@ resource "foo" "bar" { ... } **Note:** This comment must start at the immediate first line of the `.tf` file before any `resource`, `variable`, `module`, etc. +**Note:** we will never alter line-endings of extracted header text and will assume +whatever extracted is intended as is. It's up to you to apply any kind of Markdown +formatting to them (i.e. adding `` at the end of lines for break, etc.) + ## Insert Output To File Since `v0.12.0` generated output can be insterted directly into the file. There diff --git a/examples/doc.adoc b/examples/doc.adoc index ffe215c..9412641 100644 --- a/examples/doc.adoc +++ b/examples/doc.adoc @@ -3,6 +3,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation -ullamco laboris nisi ut aliquip ex ea commodo consequat. +ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit -esse cillum dolore eu fugiat nulla pariatur. +esse cillum dolore eu fugiat nulla pariatur. \ No newline at end of file diff --git a/examples/doc.md b/examples/doc.md index 79b0ef9..1ef23fb 100644 --- a/examples/doc.md +++ b/examples/doc.md @@ -3,6 +3,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation -ullamco laboris nisi ut aliquip ex ea commodo consequat. +ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit -esse cillum dolore eu fugiat nulla pariatur. +esse cillum dolore eu fugiat nulla pariatur. \ No newline at end of file diff --git a/examples/doc.tf b/examples/doc.tf index bd2c24e..b6ac0da 100644 --- a/examples/doc.tf +++ b/examples/doc.tf @@ -4,7 +4,7 @@ * Lorem ipsum dolor sit amet, consectetur adipiscing elit, * sed do eiusmod tempor incididunt ut labore et dolore magna * aliqua. Ut enim ad minim veniam, quis nostrud exercitation - * ullamco laboris nisi ut aliquip ex ea commodo consequat. + * ullamco laboris nisi ut aliquip ex ea commodo consequat. * Duis aute irure dolor in reprehenderit in voluptate velit * esse cillum dolore eu fugiat nulla pariatur. */ diff --git a/examples/doc.txt b/examples/doc.txt index 6ccbbd6..0cea7bc 100644 --- a/examples/doc.txt +++ b/examples/doc.txt @@ -3,6 +3,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation -ullamco laboris nisi ut aliquip ex ea commodo consequat. +ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit -esse cillum dolore eu fugiat nulla pariatur. +esse cillum dolore eu fugiat nulla pariatur. \ No newline at end of file diff --git a/internal/format/common_test.go b/internal/format/common_test.go index c4fe5e1..b4ddb34 100644 --- a/internal/format/common_test.go +++ b/internal/format/common_test.go @@ -77,22 +77,22 @@ func TestCommonSort(t *testing.T) { assert.Nil(err) for ii, i := range module.Inputs { - assert.Equal(i.Name, expected.Inputs[ii]) + assert.Equal(expected.Inputs[ii], i.Name) } for ii, m := range module.ModuleCalls { - assert.Equal(m.Name+"-"+m.Source, expected.Modules[ii]) + assert.Equal(expected.Modules[ii], m.Name+"-"+m.Source) } for ii, o := range module.Outputs { - assert.Equal(o.Name, expected.Outputs[ii]) + assert.Equal(expected.Outputs[ii], o.Name) } for ii, p := range module.Providers { - assert.Equal(p.FullName(), expected.Providers[ii]) + assert.Equal(expected.Providers[ii], p.FullName()) } for ii, r := range module.Requirements { - assert.Equal(r.Name, expected.Requirements[ii]) + assert.Equal(expected.Requirements[ii], r.Name) } for ii, r := range module.Resources { - assert.Equal(r.FullType()+"__"+r.Mode+"."+r.Name, expected.Resources[ii]) + assert.Equal(expected.Resources[ii], r.FullType()+"__"+r.Mode+"."+r.Name) } }) } @@ -136,7 +136,7 @@ func TestCommonHeaderFrom(t *testing.T) { module, err := testutil.GetModule(options) assert.Nil(err) - assert.Equal(module.Header, expected) + assert.Equal(expected, module.Header) }) } } diff --git a/internal/format/templates/markdown_table.tmpl b/internal/format/templates/markdown_table.tmpl index bc7aa49..fbbca36 100644 --- a/internal/format/templates/markdown_table.tmpl +++ b/internal/format/templates/markdown_table.tmpl @@ -75,12 +75,12 @@ {{- if .Settings.ShowDefault }}---------|{{ end }} {{- if .Settings.ShowRequired }}:--------:|{{ end }} {{- range .Module.Inputs }} - | {{ anchorName "input" .Name }} | {{ tostring .Description | sanitizeTbl }} | + | {{ anchorName "input" .Name }} | {{ tostring .Description | sanitizeMarkdownTbl }} | {{- if $.Settings.ShowType -}} - {{ printf " " }}{{ tostring .Type | type | sanitizeTbl }} | + {{ printf " " }}{{ tostring .Type | type | sanitizeMarkdownTbl }} | {{- end -}} {{- if $.Settings.ShowDefault -}} - {{ printf " " }}{{ value .GetValue | sanitizeTbl }} | + {{ printf " " }}{{ value .GetValue | sanitizeMarkdownTbl }} | {{- end -}} {{- if $.Settings.ShowRequired -}} {{ printf " " }}{{ ternary .Required "yes" "no" }} | @@ -97,10 +97,10 @@ | Name | Description |{{ if .Settings.OutputValues }} Value |{{ if $.Settings.ShowSensitivity }} Sensitive |{{ end }}{{ end }} |------|-------------|{{ if .Settings.OutputValues }}-------|{{ if $.Settings.ShowSensitivity }}:---------:|{{ end }}{{ end }} {{- range .Module.Outputs }} - | {{ anchorName "output" .Name }} | {{ tostring .Description | sanitizeTbl }} | + | {{ anchorName "output" .Name }} | {{ tostring .Description | sanitizeMarkdownTbl }} | {{- if $.Settings.OutputValues -}} {{- $sensitive := ternary .Sensitive "" .GetValue -}} - {{ printf " " }}{{ value $sensitive | sanitizeTbl }} | + {{ printf " " }}{{ value $sensitive | sanitizeMarkdownTbl }} | {{- if $.Settings.ShowSensitivity -}} {{ printf " " }}{{ ternary .Sensitive "yes" "no" }} | {{- end -}} diff --git a/internal/format/testdata/asciidoc/document-Base.golden b/internal/format/testdata/asciidoc/document-Base.golden index 143d068..646a9ad 100644 --- a/internal/format/testdata/asciidoc/document-Base.golden +++ b/internal/format/testdata/asciidoc/document-Base.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/document-IndentationOfFour.golden b/internal/format/testdata/asciidoc/document-IndentationOfFour.golden index 0b5d7dd..cb31196 100644 --- a/internal/format/testdata/asciidoc/document-IndentationOfFour.golden +++ b/internal/format/testdata/asciidoc/document-IndentationOfFour.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/document-OnlyHeader.golden b/internal/format/testdata/asciidoc/document-OnlyHeader.golden index 138e1b4..303e201 100644 --- a/internal/format/testdata/asciidoc/document-OnlyHeader.golden +++ b/internal/format/testdata/asciidoc/document-OnlyHeader.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/document-WithAnchor.golden b/internal/format/testdata/asciidoc/document-WithAnchor.golden index 79546ae..5dd88df 100644 --- a/internal/format/testdata/asciidoc/document-WithAnchor.golden +++ b/internal/format/testdata/asciidoc/document-WithAnchor.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/document-WithRequired.golden b/internal/format/testdata/asciidoc/document-WithRequired.golden index 24127a1..9b6ea14 100644 --- a/internal/format/testdata/asciidoc/document-WithRequired.golden +++ b/internal/format/testdata/asciidoc/document-WithRequired.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/table-Base.golden b/internal/format/testdata/asciidoc/table-Base.golden index 0be3640..b29d34f 100644 --- a/internal/format/testdata/asciidoc/table-Base.golden +++ b/internal/format/testdata/asciidoc/table-Base.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/table-IndentationOfFour.golden b/internal/format/testdata/asciidoc/table-IndentationOfFour.golden index 38be4f2..d85b6b0 100644 --- a/internal/format/testdata/asciidoc/table-IndentationOfFour.golden +++ b/internal/format/testdata/asciidoc/table-IndentationOfFour.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/table-OnlyHeader.golden b/internal/format/testdata/asciidoc/table-OnlyHeader.golden index 138e1b4..303e201 100644 --- a/internal/format/testdata/asciidoc/table-OnlyHeader.golden +++ b/internal/format/testdata/asciidoc/table-OnlyHeader.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/table-WithAnchor.golden b/internal/format/testdata/asciidoc/table-WithAnchor.golden index 4720e0b..cb0b374 100644 --- a/internal/format/testdata/asciidoc/table-WithAnchor.golden +++ b/internal/format/testdata/asciidoc/table-WithAnchor.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/asciidoc/table-WithRequired.golden b/internal/format/testdata/asciidoc/table-WithRequired.golden index 1652659..942ad64 100644 --- a/internal/format/testdata/asciidoc/table-WithRequired.golden +++ b/internal/format/testdata/asciidoc/table-WithRequired.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/common/header-HeaderFromADOCFile.golden b/internal/format/testdata/common/header-HeaderFromADOCFile.golden index ffe215c..9412641 100644 --- a/internal/format/testdata/common/header-HeaderFromADOCFile.golden +++ b/internal/format/testdata/common/header-HeaderFromADOCFile.golden @@ -3,6 +3,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation -ullamco laboris nisi ut aliquip ex ea commodo consequat. +ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit -esse cillum dolore eu fugiat nulla pariatur. +esse cillum dolore eu fugiat nulla pariatur. \ No newline at end of file diff --git a/internal/format/testdata/common/header-HeaderFromMDFile.golden b/internal/format/testdata/common/header-HeaderFromMDFile.golden index 79b0ef9..1ef23fb 100644 --- a/internal/format/testdata/common/header-HeaderFromMDFile.golden +++ b/internal/format/testdata/common/header-HeaderFromMDFile.golden @@ -3,6 +3,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation -ullamco laboris nisi ut aliquip ex ea commodo consequat. +ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit -esse cillum dolore eu fugiat nulla pariatur. +esse cillum dolore eu fugiat nulla pariatur. \ No newline at end of file diff --git a/internal/format/testdata/common/header-HeaderFromTFFile.golden b/internal/format/testdata/common/header-HeaderFromTFFile.golden index f812613..f1e78ee 100644 --- a/internal/format/testdata/common/header-HeaderFromTFFile.golden +++ b/internal/format/testdata/common/header-HeaderFromTFFile.golden @@ -3,6 +3,6 @@ This header comes from a custom file Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation -ullamco laboris nisi ut aliquip ex ea commodo consequat. +ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. \ No newline at end of file diff --git a/internal/format/testdata/common/header-HeaderFromTXTFile.golden b/internal/format/testdata/common/header-HeaderFromTXTFile.golden index 6ccbbd6..0cea7bc 100644 --- a/internal/format/testdata/common/header-HeaderFromTXTFile.golden +++ b/internal/format/testdata/common/header-HeaderFromTXTFile.golden @@ -3,6 +3,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation -ullamco laboris nisi ut aliquip ex ea commodo consequat. +ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit -esse cillum dolore eu fugiat nulla pariatur. +esse cillum dolore eu fugiat nulla pariatur. \ No newline at end of file diff --git a/internal/format/testdata/markdown/document-Base.golden b/internal/format/testdata/markdown/document-Base.golden index f251474..cb2f69d 100644 --- a/internal/format/testdata/markdown/document-Base.golden +++ b/internal/format/testdata/markdown/document-Base.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/document-EscapeCharacters.golden b/internal/format/testdata/markdown/document-EscapeCharacters.golden index 27ba5e0..ebe127f 100644 --- a/internal/format/testdata/markdown/document-EscapeCharacters.golden +++ b/internal/format/testdata/markdown/document-EscapeCharacters.golden @@ -5,7 +5,7 @@ Example of 'foo\_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/document-IndentationOfFour.golden b/internal/format/testdata/markdown/document-IndentationOfFour.golden index 8b36c6f..e2eafbe 100644 --- a/internal/format/testdata/markdown/document-IndentationOfFour.golden +++ b/internal/format/testdata/markdown/document-IndentationOfFour.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/document-OnlyHeader.golden b/internal/format/testdata/markdown/document-OnlyHeader.golden index 138e1b4..303e201 100644 --- a/internal/format/testdata/markdown/document-OnlyHeader.golden +++ b/internal/format/testdata/markdown/document-OnlyHeader.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/document-WithAnchor.golden b/internal/format/testdata/markdown/document-WithAnchor.golden index f6d3afd..0fc337a 100644 --- a/internal/format/testdata/markdown/document-WithAnchor.golden +++ b/internal/format/testdata/markdown/document-WithAnchor.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/document-WithRequired.golden b/internal/format/testdata/markdown/document-WithRequired.golden index dbdd2cc..3870413 100644 --- a/internal/format/testdata/markdown/document-WithRequired.golden +++ b/internal/format/testdata/markdown/document-WithRequired.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/table-Base.golden b/internal/format/testdata/markdown/table-Base.golden index 17631a8..4d082f7 100644 --- a/internal/format/testdata/markdown/table-Base.golden +++ b/internal/format/testdata/markdown/table-Base.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/table-EscapeCharacters.golden b/internal/format/testdata/markdown/table-EscapeCharacters.golden index e2c1308..1f100d7 100644 --- a/internal/format/testdata/markdown/table-EscapeCharacters.golden +++ b/internal/format/testdata/markdown/table-EscapeCharacters.golden @@ -5,7 +5,7 @@ Example of 'foo\_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/table-IndentationOfFour.golden b/internal/format/testdata/markdown/table-IndentationOfFour.golden index cecde06..0d58440 100644 --- a/internal/format/testdata/markdown/table-IndentationOfFour.golden +++ b/internal/format/testdata/markdown/table-IndentationOfFour.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/table-OnlyHeader.golden b/internal/format/testdata/markdown/table-OnlyHeader.golden index 138e1b4..303e201 100644 --- a/internal/format/testdata/markdown/table-OnlyHeader.golden +++ b/internal/format/testdata/markdown/table-OnlyHeader.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/table-WithAnchor.golden b/internal/format/testdata/markdown/table-WithAnchor.golden index 188d068..0ce7265 100644 --- a/internal/format/testdata/markdown/table-WithAnchor.golden +++ b/internal/format/testdata/markdown/table-WithAnchor.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/format/testdata/markdown/table-WithRequired.golden b/internal/format/testdata/markdown/table-WithRequired.golden index c05bc59..c0ee289 100644 --- a/internal/format/testdata/markdown/table-WithRequired.golden +++ b/internal/format/testdata/markdown/table-WithRequired.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 @@ -28,7 +28,7 @@ module "foo_bar" { } ``` -Here is some trailing text after code block, +Here is some trailing text after code block, followed by another line of text. | Name | Description | diff --git a/internal/template/sanitizer.go b/internal/template/sanitizer.go index 3230974..3176eae 100644 --- a/internal/template/sanitizer.go +++ b/internal/template/sanitizer.go @@ -30,9 +30,12 @@ func sanitizeName(name string, settings *print.Settings) string { return name } -// sanitizeItemForDocument converts passed 'string' to suitable Markdown representation +// sanitizeHeader converts passed 'string' to suitable Markdown representation // for a document. (including line-break, illegal characters, code blocks etc) -func sanitizeItemForDocument(s string, settings *print.Settings) string { +// +// IMPORTANT: sanitizeHeader will never change the line-endings and preserve them +// as they are provided by the users. +func sanitizeHeader(s string, settings *print.Settings) string { if s == "" { return "n/a" } @@ -41,7 +44,7 @@ func sanitizeItemForDocument(s string, settings *print.Settings) string { "```", func(segment string) string { segment = escapeIllegalCharacters(segment, settings, false) - segment = convertMultiLineText(segment, false) + segment = convertMultiLineText(segment, false, true) segment = normalizeURLs(segment, settings) return segment }, @@ -57,9 +60,37 @@ func sanitizeItemForDocument(s string, settings *print.Settings) string { return result } -// sanitizeItemForTable converts passed 'string' to suitable Markdown representation +// sanitizeDocument converts passed 'string' to suitable Markdown or AsciiDoc +// representation for a document. (including line-break, illegal characters, +// code blocks etc) +func sanitizeDocument(s string, settings *print.Settings) string { + if s == "" { + return "n/a" + } + result := processSegments( + s, + "```", + func(segment string) string { + segment = escapeIllegalCharacters(segment, settings, false) + segment = convertMultiLineText(segment, false, false) + segment = normalizeURLs(segment, settings) + return segment + }, + func(segment string) string { + lastbreak := "" + if !strings.HasSuffix(segment, "\n") { + lastbreak = "\n" + } + segment = fmt.Sprintf("```%s%s```", segment, lastbreak) + return segment + }, + ) + return result +} + +// sanitizeMarkdownTable converts passed 'string' to suitable Markdown representation // for a table. (including line-break, illegal characters, code blocks etc) -func sanitizeItemForTable(s string, settings *print.Settings) string { +func sanitizeMarkdownTable(s string, settings *print.Settings) string { if s == "" { return "n/a" } @@ -68,7 +99,7 @@ func sanitizeItemForTable(s string, settings *print.Settings) string { "```", func(segment string) string { segment = escapeIllegalCharacters(segment, settings, true) - segment = convertMultiLineText(segment, true) + segment = convertMultiLineText(segment, true, false) segment = normalizeURLs(segment, settings) return segment }, @@ -83,9 +114,9 @@ func sanitizeItemForTable(s string, settings *print.Settings) string { return result } -// sanitizeItemForAsciidocTable converts passed 'string' to suitable AsciiDoc representation +// sanitizeAsciidocTable converts passed 'string' to suitable AsciiDoc representation // for a table. (including line-break, illegal characters, code blocks etc) -func sanitizeItemForAsciidocTable(s string, settings *print.Settings) string { +func sanitizeAsciidocTable(s string, settings *print.Settings) string { if s == "" { return "n/a" } @@ -107,7 +138,7 @@ func sanitizeItemForAsciidocTable(s string, settings *print.Settings) string { } // convertMultiLineText converts a multi-line text into a suitable Markdown representation. -func convertMultiLineText(s string, isTable bool) string { +func convertMultiLineText(s string, isTable bool, isHeader bool) string { if isTable { s = strings.TrimSpace(s) } @@ -120,9 +151,11 @@ func convertMultiLineText(s string, isTable bool) string { // which is a know convention of Markdown for multi-lines paragprah. // This doesn't apply on a markdown list for example, because all the // consecutive lines start with hyphen which is a special character. - s = regexp.MustCompile(`(\S*)(\r?\n)(\s*)(\w+)`).ReplaceAllString(s, "$1 $2$3$4") - s = strings.Replace(s, " \n", " \n", -1) - s = strings.Replace(s, "
\n", "\n\n", -1) + if !isHeader { + s = regexp.MustCompile(`(\S*)(\r?\n)(\s*)(\w+)`).ReplaceAllString(s, "$1 $2$3$4") + s = strings.Replace(s, " \n", " \n", -1) + s = strings.Replace(s, "
\n", "\n\n", -1) + } if isTable { // Convert space-space-newline to
diff --git a/internal/template/sanitizer_test.go b/internal/template/sanitizer_test.go index ae69d5d..3014f68 100644 --- a/internal/template/sanitizer_test.go +++ b/internal/template/sanitizer_test.go @@ -107,7 +107,49 @@ func TestSanitizeName(t *testing.T) { } } -func TestSanitizeItemForDocument(t *testing.T) { +func TestSanitizeHeader(t *testing.T) { + tests := []struct { + name string + filename string + escape bool + }{ + { + name: "sanitize header item empty", + filename: "empty", + escape: true, + }, + { + name: "sanitize header item complex", + filename: "complex", + escape: true, + }, + { + name: "sanitize header item codeblock", + filename: "codeblock", + escape: true, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + assert := assert.New(t) + settings := &print.Settings{ + EscapeCharacters: tt.escape, + } + + bytes, err := ioutil.ReadFile(filepath.Join("testdata", "header", tt.filename+".golden")) + assert.Nil(err) + + actual := sanitizeHeader(string(bytes), settings) + + expected, err := ioutil.ReadFile(filepath.Join("testdata", "header", tt.filename+".expected")) + assert.Nil(err) + + assert.Equal(string(expected), actual) + }) + } +} + +func TestSanitizeDocument(t *testing.T) { tests := []struct { name string filename string @@ -139,7 +181,7 @@ func TestSanitizeItemForDocument(t *testing.T) { bytes, err := ioutil.ReadFile(filepath.Join("testdata", "document", tt.filename+".golden")) assert.Nil(err) - actual := sanitizeItemForDocument(string(bytes), settings) + actual := sanitizeDocument(string(bytes), settings) expected, err := ioutil.ReadFile(filepath.Join("testdata", "document", tt.filename+".expected")) assert.Nil(err) @@ -149,7 +191,7 @@ func TestSanitizeItemForDocument(t *testing.T) { } } -func TestSanitizeItemForTable(t *testing.T) { +func TestSanitizeMarkdownTable(t *testing.T) { tests := []struct { name string filename string @@ -181,7 +223,7 @@ func TestSanitizeItemForTable(t *testing.T) { bytes, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".golden")) assert.Nil(err) - actual := sanitizeItemForTable(string(bytes), settings) + actual := sanitizeMarkdownTable(string(bytes), settings) expected, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".expected")) assert.Nil(err) @@ -191,7 +233,7 @@ func TestSanitizeItemForTable(t *testing.T) { } } -func TestSanitizeItemForAsciidocTable(t *testing.T) { +func TestSanitizeAsciidocTable(t *testing.T) { tests := []struct { name string filename string @@ -223,7 +265,7 @@ func TestSanitizeItemForAsciidocTable(t *testing.T) { bytes, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".golden")) assert.Nil(err) - actual := sanitizeItemForAsciidocTable(string(bytes), settings) + actual := sanitizeAsciidocTable(string(bytes), settings) expected, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".asciidoc.expected")) assert.Nil(err) @@ -309,7 +351,7 @@ func TestConvertMultiLineText(t *testing.T) { bytes, err := ioutil.ReadFile(path) assert.Nil(err) - actual := convertMultiLineText(string(bytes), tt.isTable) + actual := convertMultiLineText(string(bytes), tt.isTable, false) assert.Equal(tt.expected, actual) }) } diff --git a/internal/template/template.go b/internal/template/template.go index 4947071..2a1ac6b 100644 --- a/internal/template/template.go +++ b/internal/template/template.go @@ -47,16 +47,16 @@ func New(settings *print.Settings, items ...*Item) *Template { return string(s) }, "sanitizeHeader": func(s string) string { - return sanitizeItemForDocument(s, settings) + return sanitizeHeader(s, settings) }, "sanitizeDoc": func(s string) string { - return sanitizeItemForDocument(s, settings) + return sanitizeDocument(s, settings) }, - "sanitizeTbl": func(s string) string { - return sanitizeItemForTable(s, settings) + "sanitizeMarkdownTbl": func(s string) string { + return sanitizeMarkdownTable(s, settings) }, "sanitizeAsciidocTbl": func(s string) string { - return sanitizeItemForAsciidocTable(s, settings) + return sanitizeAsciidocTable(s, settings) }, "anchorName": func(s string, t string) string { return createAnchorMarkdown(s, t, settings) diff --git a/internal/template/template_test.go b/internal/template/template_test.go index 38156d7..3bd9038 100644 --- a/internal/template/template_test.go +++ b/internal/template/template_test.go @@ -392,24 +392,24 @@ func TestBuiltinFunc(t *testing.T) { expected: "n/a", }, - // sanitizeTbl + // sanitizeMarkdownTbl { - name: "template builtin functions sanitizeTbl", - funcName: "sanitizeTbl", + name: "template builtin functions sanitizeMarkdownTbl", + funcName: "sanitizeMarkdownTbl", funcArgs: []string{"\"Example of 'foo_bar' module in `foo_bar.tf`.\n\n| Foo | Bar |\""}, escape: true, expected: "Example of 'foo\\_bar' module in `foo_bar.tf`.

\\| Foo \\| Bar \\|", }, { - name: "template builtin functions sanitizeTbl", - funcName: "sanitizeTbl", + name: "template builtin functions sanitizeMarkdownTbl", + funcName: "sanitizeMarkdownTbl", funcArgs: []string{"\"Example of 'foo_bar' module in `foo_bar.tf`.\n\n| Foo | Bar |\""}, escape: false, expected: "Example of 'foo_bar' module in `foo_bar.tf`.

\\| Foo \\| Bar \\|", }, { - name: "template builtin functions sanitizeTbl", - funcName: "sanitizeTbl", + name: "template builtin functions sanitizeMarkdownTbl", + funcName: "sanitizeMarkdownTbl", funcArgs: []string{`""`}, escape: true, expected: "n/a", diff --git a/internal/template/testdata/document/complex.golden b/internal/template/testdata/document/complex.golden index 303e201..d3b77d3 100644 --- a/internal/template/testdata/document/complex.golden +++ b/internal/template/testdata/document/complex.golden @@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`. - list item 1 - list item 2 -Even inline **formatting** in _here_ is possible. +Even inline **formatting** in _here_ is possible. and some [link](https://domain.com/) * list item 3 diff --git a/internal/template/testdata/header/codeblock.expected b/internal/template/testdata/header/codeblock.expected new file mode 100644 index 0000000..03e3ad3 --- /dev/null +++ b/internal/template/testdata/header/codeblock.expected @@ -0,0 +1,9 @@ +This is a complicated one. We need a newline. +And an example in a code block. Availeble options +are: foo | bar | baz + +``` +default = [ + "foo" +] +``` \ No newline at end of file diff --git a/internal/template/testdata/header/codeblock.golden b/internal/template/testdata/header/codeblock.golden new file mode 100644 index 0000000..4e81a60 --- /dev/null +++ b/internal/template/testdata/header/codeblock.golden @@ -0,0 +1,8 @@ +This is a complicated one. We need a newline. +And an example in a code block. Availeble options +are: foo | bar | baz + +``` +default = [ + "foo" +]``` \ No newline at end of file diff --git a/internal/template/testdata/header/complex.expected b/internal/template/testdata/header/complex.expected new file mode 100644 index 0000000..d284951 --- /dev/null +++ b/internal/template/testdata/header/complex.expected @@ -0,0 +1,37 @@ +Usage: + +Example of 'foo\_bar' module in `foo_bar.tf`. + +- list item 1 +- list item 2 + +Even inline **formatting** in _here_ is possible. +and some [link](https://domain.com/) + +* list item 3 +* list item 4 + +```hcl +module "foo_bar" { + source = "github.com/foo/bar" + + id = "1234567890" + name = "baz" + + zones = ["us-east-1", "us-west-1"] + + tags = { + Name = "baz" + Created-By = "first.last@email.com" + Date-Created = "20180101" + } +} +``` + +Here is some trailing text after code block, +followed by another line of text. + +| Name | Description | +|------|-----------------| +| Foo | Foo description | +| Bar | Bar description | \ No newline at end of file diff --git a/internal/template/testdata/header/complex.golden b/internal/template/testdata/header/complex.golden new file mode 100644 index 0000000..d3b77d3 --- /dev/null +++ b/internal/template/testdata/header/complex.golden @@ -0,0 +1,37 @@ +Usage: + +Example of 'foo_bar' module in `foo_bar.tf`. + +- list item 1 +- list item 2 + +Even inline **formatting** in _here_ is possible. +and some [link](https://domain.com/) + +* list item 3 +* list item 4 + +```hcl +module "foo_bar" { + source = "github.com/foo/bar" + + id = "1234567890" + name = "baz" + + zones = ["us-east-1", "us-west-1"] + + tags = { + Name = "baz" + Created-By = "first.last@email.com" + Date-Created = "20180101" + } +} +``` + +Here is some trailing text after code block, +followed by another line of text. + +| Name | Description | +|------|-----------------| +| Foo | Foo description | +| Bar | Bar description | \ No newline at end of file diff --git a/internal/template/testdata/header/empty.expected b/internal/template/testdata/header/empty.expected new file mode 100644 index 0000000..d8e0871 --- /dev/null +++ b/internal/template/testdata/header/empty.expected @@ -0,0 +1 @@ +n/a \ No newline at end of file diff --git a/internal/template/testdata/header/empty.golden b/internal/template/testdata/header/empty.golden new file mode 100644 index 0000000..e69de29 diff --git a/internal/terraform/module.go b/internal/terraform/module.go index 7951f49..61a36a3 100644 --- a/internal/terraform/module.go +++ b/internal/terraform/module.go @@ -205,13 +205,15 @@ func loadHeader(options *Options) (string, error) { return strings.HasPrefix(line, "/*") || strings.HasPrefix(line, "*") || strings.HasPrefix(line, "*/") }, Parser: func(line string) (string, bool) { - line = strings.TrimSpace(line) - if strings.HasPrefix(line, "/*") || strings.HasPrefix(line, "*/") { + tmp := strings.TrimSpace(line) + if strings.HasPrefix(tmp, "/*") || strings.HasPrefix(tmp, "*/") { return "", false } - if line == "*" { + if tmp == "*" { return "", true } + line = strings.TrimLeft(line, " ") + line = strings.TrimRight(line, "\r\n") line = strings.TrimPrefix(line, "* ") return line, true },