centersl/terraform-docs
1
0
Fork 0
mirror of https://github.com/terraform-docs/terraform-docs.git synced 2026-03-27 12:58:35 +07:00
Code Issues Packages Projects Releases Wiki Activity

Do not modify header lines and trailing whitespaces

Browse Source 
This is going to preserve line-ending of extracted header text as they
are provided by users. In other words we are going to always assume the
header text is formatted in the "intended" way by users. So we're never
going to modify line-endings and won't append `<SPACE><SPACE>` at the
end of paragraph lines.

Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>
This commit is contained in:
Khosrow Moossavi
2021-03-12 18:56:30 -05:00
parent 5468410625
commit 7e489d2bbb
50 changed files with 297 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.editorconfig
View File

@@ -16,6 +16,13 @@ insert_final_newline = true
indent_style = tab indent_style = tab
indent_size = 4 indent_size = 4
[*.md]
trim_trailing_whitespace = true
[examples/doc.{adoc,md,tf,txt}]
trim_trailing_whitespace = false
insert_final_newline = false
[*.{golden,tmpl}] [*.{golden,tmpl}]
trim_trailing_whitespace = false trim_trailing_whitespace = false
insert_final_newline = false insert_final_newline = false

4
docs/reference/asciidoc-document.md
View File

@@ -64,7 +64,7 @@ generates the following output:
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
docs/reference/asciidoc-table.md
View File

@@ -64,7 +64,7 @@ generates the following output:
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
docs/reference/markdown-document.md
View File

@@ -65,7 +65,7 @@ generates the following output:
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
docs/reference/markdown-table.md
View File

@@ -65,7 +65,7 @@ generates the following output:
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

11
docs/user-guide/how-to.md
View File

@@ -27,8 +27,9 @@ terraform-docs --hide-all --show inputs --show outputs ... # hide all sections e
## Module Header ## Module Header
Module header can be extracted from different sources. Default file to extract 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`. header from is `main.tf`, otherwise you can specify the file with `--header-from FILE`
Supported file formats to read header from are: or corresponding `header-from` in configuration file. Supported file formats to
read header from are:
- `.adoc` - `.adoc`
- `.md` - `.md`
@@ -36,7 +37,7 @@ Supported file formats to read header from are:
- `.txt` - `.txt`
The whole file content is being extracted as module header when extracting from 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: following javascript, c or java like multi-line comment:
```tf ```tf
@@ -57,6 +58,10 @@ resource "foo" "bar" { ... }
**Note:** This comment must start at the immediate first line of the `.tf` file **Note:** This comment must start at the immediate first line of the `.tf` file
before any `resource`, `variable`, `module`, etc. 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 `<SPACE><SPACE>` at the end of lines for break, etc.)
## Insert Output To File ## Insert Output To File
Since `v0.12.0` generated output can be insterted directly into the file. There Since `v0.12.0` generated output can be insterted directly into the file. There

4
examples/doc.adoc
View File

@@ -3,6 +3,6 @@
Lorem ipsum dolor sit amet, consectetur adipiscing elit, Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation 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 Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. esse cillum dolore eu fugiat nulla pariatur.

4
examples/doc.md
View File

@@ -3,6 +3,6 @@
Lorem ipsum dolor sit amet, consectetur adipiscing elit, Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation 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 Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. esse cillum dolore eu fugiat nulla pariatur.

2
examples/doc.tf
View File

@@ -4,7 +4,7 @@
* Lorem ipsum dolor sit amet, consectetur adipiscing elit, * Lorem ipsum dolor sit amet, consectetur adipiscing elit,
* sed do eiusmod tempor incididunt ut labore et dolore magna * sed do eiusmod tempor incididunt ut labore et dolore magna
* aliqua. Ut enim ad minim veniam, quis nostrud exercitation * 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 * Duis aute irure dolor in reprehenderit in voluptate velit
* esse cillum dolore eu fugiat nulla pariatur. * esse cillum dolore eu fugiat nulla pariatur.
*/ */

4
examples/doc.txt
View File

@@ -3,6 +3,6 @@
Lorem ipsum dolor sit amet, consectetur adipiscing elit, Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation 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 Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. esse cillum dolore eu fugiat nulla pariatur.

14
internal/format/common_test.go
View File

@@ -77,22 +77,22 @@ func TestCommonSort(t *testing.T) {
assert.Nil(err) assert.Nil(err)
for ii, i := range module.Inputs { 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 { 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 { 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 { 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 { 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 { 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) module, err := testutil.GetModule(options)
assert.Nil(err) assert.Nil(err)
assert.Equal(module.Header, expected) assert.Equal(expected, module.Header)
}) })
} }
} }

10
internal/format/templates/markdown_table.tmpl
View File

@@ -75,12 +75,12 @@
{{- if .Settings.ShowDefault }}---------|{{ end }} {{- if .Settings.ShowDefault }}---------|{{ end }}
{{- if .Settings.ShowRequired }}:--------:|{{ end }} {{- if .Settings.ShowRequired }}:--------:|{{ end }}
{{- range .Module.Inputs }} {{- range .Module.Inputs }}
| {{ anchorName "input" .Name }} | {{ tostring .Description | sanitizeTbl }} | | {{ anchorName "input" .Name }} | {{ tostring .Description | sanitizeMarkdownTbl }} |
{{- if $.Settings.ShowType -}} {{- if $.Settings.ShowType -}}
{{ printf " " }}{{ tostring .Type | type | sanitizeTbl }} | {{ printf " " }}{{ tostring .Type | type | sanitizeMarkdownTbl }} |
{{- end -}} {{- end -}}
{{- if $.Settings.ShowDefault -}} {{- if $.Settings.ShowDefault -}}
{{ printf " " }}{{ value .GetValue | sanitizeTbl }} | {{ printf " " }}{{ value .GetValue | sanitizeMarkdownTbl }} |
{{- end -}} {{- end -}}
{{- if $.Settings.ShowRequired -}} {{- if $.Settings.ShowRequired -}}
{{ printf " " }}{{ ternary .Required "yes" "no" }} | {{ printf " " }}{{ ternary .Required "yes" "no" }} |
@@ -97,10 +97,10 @@
| Name | Description |{{ if .Settings.OutputValues }} Value |{{ if $.Settings.ShowSensitivity }} Sensitive |{{ end }}{{ end }} | Name | Description |{{ if .Settings.OutputValues }} Value |{{ if $.Settings.ShowSensitivity }} Sensitive |{{ end }}{{ end }}
|------|-------------|{{ if .Settings.OutputValues }}-------|{{ if $.Settings.ShowSensitivity }}:---------:|{{ end }}{{ end }} |------|-------------|{{ if .Settings.OutputValues }}-------|{{ if $.Settings.ShowSensitivity }}:---------:|{{ end }}{{ end }}
{{- range .Module.Outputs }} {{- range .Module.Outputs }}
| {{ anchorName "output" .Name }} | {{ tostring .Description | sanitizeTbl }} | | {{ anchorName "output" .Name }} | {{ tostring .Description | sanitizeMarkdownTbl }} |
{{- if $.Settings.OutputValues -}} {{- if $.Settings.OutputValues -}}
{{- $sensitive := ternary .Sensitive "<sensitive>" .GetValue -}} {{- $sensitive := ternary .Sensitive "<sensitive>" .GetValue -}}
{{ printf " " }}{{ value $sensitive | sanitizeTbl }} | {{ printf " " }}{{ value $sensitive | sanitizeMarkdownTbl }} |
{{- if $.Settings.ShowSensitivity -}} {{- if $.Settings.ShowSensitivity -}}
{{ printf " " }}{{ ternary .Sensitive "yes" "no" }} | {{ printf " " }}{{ ternary .Sensitive "yes" "no" }} |
{{- end -}} {{- end -}}

4
internal/format/testdata/asciidoc/document-Base.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/document-IndentationOfFour.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/document-OnlyHeader.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/document-WithAnchor.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/document-WithRequired.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/table-Base.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/table-IndentationOfFour.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/table-OnlyHeader.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/table-WithAnchor.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/asciidoc/table-WithRequired.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/common/header-HeaderFromADOCFile.golden vendored
View File

@@ -3,6 +3,6 @@
Lorem ipsum dolor sit amet, consectetur adipiscing elit, Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation 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 Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. esse cillum dolore eu fugiat nulla pariatur.

4
internal/format/testdata/common/header-HeaderFromMDFile.golden vendored
View File

@@ -3,6 +3,6 @@
Lorem ipsum dolor sit amet, consectetur adipiscing elit, Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation 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 Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. esse cillum dolore eu fugiat nulla pariatur.

2
internal/format/testdata/common/header-HeaderFromTFFile.golden vendored
View File

@@ -3,6 +3,6 @@ This header comes from a custom file
Lorem ipsum dolor sit amet, consectetur adipiscing elit, Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation 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 Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. esse cillum dolore eu fugiat nulla pariatur.

4
internal/format/testdata/common/header-HeaderFromTXTFile.golden vendored
View File

@@ -3,6 +3,6 @@
Lorem ipsum dolor sit amet, consectetur adipiscing elit, Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua. Ut enim ad minim veniam, quis nostrud exercitation 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 Duis aute irure dolor in reprehenderit in voluptate velit
esse cillum dolore eu fugiat nulla pariatur. esse cillum dolore eu fugiat nulla pariatur.

4
internal/format/testdata/markdown/document-Base.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/document-EscapeCharacters.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo\_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/document-IndentationOfFour.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/document-OnlyHeader.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/document-WithAnchor.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/document-WithRequired.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/table-Base.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/table-EscapeCharacters.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo\_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/table-IndentationOfFour.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/table-OnlyHeader.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/table-WithAnchor.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

4
internal/format/testdata/markdown/table-WithRequired.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * 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. followed by another line of text.
| Name | Description | | Name | Description |

57
internal/template/sanitizer.go
View File

@@ -30,9 +30,12 @@ func sanitizeName(name string, settings *print.Settings) string {
return name 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) // 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 == "" { if s == "" {
return "n/a" return "n/a"
} }
@@ -41,7 +44,7 @@ func sanitizeItemForDocument(s string, settings *print.Settings) string {
"```", "```",
func(segment string) string { func(segment string) string {
segment = escapeIllegalCharacters(segment, settings, false) segment = escapeIllegalCharacters(segment, settings, false)
segment = convertMultiLineText(segment, false) segment = convertMultiLineText(segment, false, true)
segment = normalizeURLs(segment, settings) segment = normalizeURLs(segment, settings)
return segment return segment
}, },
@@ -57,9 +60,37 @@ func sanitizeItemForDocument(s string, settings *print.Settings) string {
return result 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) // 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 == "" { if s == "" {
return "n/a" return "n/a"
} }
@@ -68,7 +99,7 @@ func sanitizeItemForTable(s string, settings *print.Settings) string {
"```", "```",
func(segment string) string { func(segment string) string {
segment = escapeIllegalCharacters(segment, settings, true) segment = escapeIllegalCharacters(segment, settings, true)
segment = convertMultiLineText(segment, true) segment = convertMultiLineText(segment, true, false)
segment = normalizeURLs(segment, settings) segment = normalizeURLs(segment, settings)
return segment return segment
}, },
@@ -83,9 +114,9 @@ func sanitizeItemForTable(s string, settings *print.Settings) string {
return result 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) // 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 == "" { if s == "" {
return "n/a" 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. // 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 { if isTable {
s = strings.TrimSpace(s) 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. // which is a know convention of Markdown for multi-lines paragprah.
// This doesn't apply on a markdown list for example, because all the // This doesn't apply on a markdown list for example, because all the
// consecutive lines start with hyphen which is a special character. // consecutive lines start with hyphen which is a special character.
s = regexp.MustCompile(`(\S*)(\r?\n)(\s*)(\w+)`).ReplaceAllString(s, "$1 $2$3$4") if !isHeader {
s = strings.Replace(s, " \n", " \n", -1) s = regexp.MustCompile(`(\S*)(\r?\n)(\s*)(\w+)`).ReplaceAllString(s, "$1 $2$3$4")
s = strings.Replace(s, "<br> \n", "\n\n", -1) s = strings.Replace(s, " \n", " \n", -1)
s = strings.Replace(s, "<br> \n", "\n\n", -1)
}
if isTable { if isTable {
// Convert space-space-newline to <br> // Convert space-space-newline to <br>

56
internal/template/sanitizer_test.go
View File

@@ -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 { tests := []struct {
name string name string
filename string filename string
@@ -139,7 +181,7 @@ func TestSanitizeItemForDocument(t *testing.T) {
bytes, err := ioutil.ReadFile(filepath.Join("testdata", "document", tt.filename+".golden")) bytes, err := ioutil.ReadFile(filepath.Join("testdata", "document", tt.filename+".golden"))
assert.Nil(err) assert.Nil(err)
actual := sanitizeItemForDocument(string(bytes), settings) actual := sanitizeDocument(string(bytes), settings)
expected, err := ioutil.ReadFile(filepath.Join("testdata", "document", tt.filename+".expected")) expected, err := ioutil.ReadFile(filepath.Join("testdata", "document", tt.filename+".expected"))
assert.Nil(err) assert.Nil(err)
@@ -149,7 +191,7 @@ func TestSanitizeItemForDocument(t *testing.T) {
} }
} }
func TestSanitizeItemForTable(t *testing.T) { func TestSanitizeMarkdownTable(t *testing.T) {
tests := []struct { tests := []struct {
name string name string
filename string filename string
@@ -181,7 +223,7 @@ func TestSanitizeItemForTable(t *testing.T) {
bytes, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".golden")) bytes, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".golden"))
assert.Nil(err) assert.Nil(err)
actual := sanitizeItemForTable(string(bytes), settings) actual := sanitizeMarkdownTable(string(bytes), settings)
expected, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".expected")) expected, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".expected"))
assert.Nil(err) assert.Nil(err)
@@ -191,7 +233,7 @@ func TestSanitizeItemForTable(t *testing.T) {
} }
} }
func TestSanitizeItemForAsciidocTable(t *testing.T) { func TestSanitizeAsciidocTable(t *testing.T) {
tests := []struct { tests := []struct {
name string name string
filename string filename string
@@ -223,7 +265,7 @@ func TestSanitizeItemForAsciidocTable(t *testing.T) {
bytes, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".golden")) bytes, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".golden"))
assert.Nil(err) 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")) expected, err := ioutil.ReadFile(filepath.Join("testdata", "table", tt.filename+".asciidoc.expected"))
assert.Nil(err) assert.Nil(err)
@@ -309,7 +351,7 @@ func TestConvertMultiLineText(t *testing.T) {
bytes, err := ioutil.ReadFile(path) bytes, err := ioutil.ReadFile(path)
assert.Nil(err) assert.Nil(err)
actual := convertMultiLineText(string(bytes), tt.isTable) actual := convertMultiLineText(string(bytes), tt.isTable, false)
assert.Equal(tt.expected, actual) assert.Equal(tt.expected, actual)
}) })
} }

10
internal/template/template.go
View File

@@ -47,16 +47,16 @@ func New(settings *print.Settings, items ...*Item) *Template {
return string(s) return string(s)
}, },
"sanitizeHeader": func(s string) string { "sanitizeHeader": func(s string) string {
return sanitizeItemForDocument(s, settings) return sanitizeHeader(s, settings)
}, },
"sanitizeDoc": func(s string) string { "sanitizeDoc": func(s string) string {
return sanitizeItemForDocument(s, settings) return sanitizeDocument(s, settings)
}, },
"sanitizeTbl": func(s string) string { "sanitizeMarkdownTbl": func(s string) string {
return sanitizeItemForTable(s, settings) return sanitizeMarkdownTable(s, settings)
}, },
"sanitizeAsciidocTbl": func(s string) string { "sanitizeAsciidocTbl": func(s string) string {
return sanitizeItemForAsciidocTable(s, settings) return sanitizeAsciidocTable(s, settings)
}, },
"anchorName": func(s string, t string) string { "anchorName": func(s string, t string) string {
return createAnchorMarkdown(s, t, settings) return createAnchorMarkdown(s, t, settings)

14
internal/template/template_test.go
View File

@@ -392,24 +392,24 @@ func TestBuiltinFunc(t *testing.T) {
expected: "n/a", expected: "n/a",
}, },
// sanitizeTbl // sanitizeMarkdownTbl
{ {
name: "template builtin functions sanitizeTbl", name: "template builtin functions sanitizeMarkdownTbl",
funcName: "sanitizeTbl", funcName: "sanitizeMarkdownTbl",
funcArgs: []string{"\"Example of 'foo_bar' module in `foo_bar.tf`.\n\n| Foo | Bar |\""}, funcArgs: []string{"\"Example of 'foo_bar' module in `foo_bar.tf`.\n\n| Foo | Bar |\""},
escape: true, escape: true,
expected: "Example of 'foo\\_bar' module in `foo_bar.tf`.<br><br>\\| Foo \\| Bar \\|", expected: "Example of 'foo\\_bar' module in `foo_bar.tf`.<br><br>\\| Foo \\| Bar \\|",
}, },
{ {
name: "template builtin functions sanitizeTbl", name: "template builtin functions sanitizeMarkdownTbl",
funcName: "sanitizeTbl", funcName: "sanitizeMarkdownTbl",
funcArgs: []string{"\"Example of 'foo_bar' module in `foo_bar.tf`.\n\n| Foo | Bar |\""}, funcArgs: []string{"\"Example of 'foo_bar' module in `foo_bar.tf`.\n\n| Foo | Bar |\""},
escape: false, escape: false,
expected: "Example of 'foo_bar' module in `foo_bar.tf`.<br><br>\\| Foo \\| Bar \\|", expected: "Example of 'foo_bar' module in `foo_bar.tf`.<br><br>\\| Foo \\| Bar \\|",
}, },
{ {
name: "template builtin functions sanitizeTbl", name: "template builtin functions sanitizeMarkdownTbl",
funcName: "sanitizeTbl", funcName: "sanitizeMarkdownTbl",
funcArgs: []string{`""`}, funcArgs: []string{`""`},
escape: true, escape: true,
expected: "n/a", expected: "n/a",

2
internal/template/testdata/document/complex.golden vendored
View File

@@ -5,7 +5,7 @@ Example of 'foo_bar' module in `foo_bar.tf`.
- list item 1 - list item 1
- list item 2 - list item 2
Even inline **formatting** in _here_ is possible. Even inline **formatting** in _here_ is possible.
and some [link](https://domain.com/) and some [link](https://domain.com/)
* list item 3 * list item 3

9
internal/template/testdata/header/codeblock.expected vendored Normal file
View File

@@ -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"
]
```

8
internal/template/testdata/header/codeblock.golden vendored Normal file
View File

@@ -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"
]```

37
internal/template/testdata/header/complex.expected vendored Normal file
View File

@@ -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 |

37
internal/template/testdata/header/complex.golden vendored Normal file
View File

@@ -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 |

1
internal/template/testdata/header/empty.expected vendored Normal file
View File

@@ -0,0 +1 @@
n/a

0
internal/template/testdata/header/empty.golden vendored Normal file
View File

8
internal/terraform/module.go
View File

@@ -205,13 +205,15 @@ func loadHeader(options *Options) (string, error) {
return strings.HasPrefix(line, "/*") || strings.HasPrefix(line, "*") || strings.HasPrefix(line, "*/") return strings.HasPrefix(line, "/*") || strings.HasPrefix(line, "*") || strings.HasPrefix(line, "*/")
}, },
Parser: func(line string) (string, bool) { Parser: func(line string) (string, bool) {
line = strings.TrimSpace(line) tmp := strings.TrimSpace(line)
if strings.HasPrefix(line, "/*") || strings.HasPrefix(line, "*/") { if strings.HasPrefix(tmp, "/*") || strings.HasPrefix(tmp, "*/") {
return "", false return "", false
} }
if line == "*" { if tmp == "*" {
return "", true return "", true
} }
line = strings.TrimLeft(line, " ")
line = strings.TrimRight(line, "\r\n")
line = strings.TrimPrefix(line, "* ") line = strings.TrimPrefix(line, "* ")
return line, true return line, true
}, },