From ffeb72c34bff17c2b0f87ef1de155f663b3c06aa Mon Sep 17 00:00:00 2001 From: Khosrow Moossavi Date: Mon, 23 Sep 2019 02:14:59 -0400 Subject: [PATCH] Add support for controlling the indentation of Markdown headers (#120) --- cmd/root.go | 1 + .../pkg/print/markdown/document/document.go | 12 +- .../print/markdown/document/document_test.go | 60 ++++++++ ...ocument-WithIndentationAboveAllowed.golden | 132 ++++++++++++++++++ ...cument-WithIndentationBellowAllowed.golden | 132 ++++++++++++++++++ .../document-WithIndentationOfFour.golden | 132 ++++++++++++++++++ internal/pkg/print/markdown/markdown.go | 16 +++ internal/pkg/print/markdown/table/table.go | 4 +- .../pkg/print/markdown/table/table_test.go | 60 ++++++++ .../table-WithIndentationAboveAllowed.golden | 41 ++++++ .../table-WithIndentationBellowAllowed.golden | 41 ++++++ .../table-WithIndentationOfFour.golden | 41 ++++++ internal/pkg/settings/settings.go | 5 + 13 files changed, 669 insertions(+), 8 deletions(-) create mode 100644 internal/pkg/print/markdown/document/testdata/document-WithIndentationAboveAllowed.golden create mode 100644 internal/pkg/print/markdown/document/testdata/document-WithIndentationBellowAllowed.golden create mode 100644 internal/pkg/print/markdown/document/testdata/document-WithIndentationOfFour.golden create mode 100644 internal/pkg/print/markdown/table/testdata/table-WithIndentationAboveAllowed.golden create mode 100644 internal/pkg/print/markdown/table/testdata/table-WithIndentationBellowAllowed.golden create mode 100644 internal/pkg/print/markdown/table/testdata/table-WithIndentationOfFour.golden diff --git a/cmd/root.go b/cmd/root.go index d39aedc..94249a9 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -37,6 +37,7 @@ func init() { markdownCmd.PersistentFlags().BoolVar(new(bool), "no-required", false, "omit \"Required\" column when generating Markdown") markdownCmd.PersistentFlags().BoolVar(new(bool), "no-escape", false, "do not escape special characters") + markdownCmd.PersistentFlags().IntVar(&settings.MarkdownIndent, "indent", 2, "indention level of Markdown sections [1, 2, 3, 4, 5]") } // Execute adds all child commands to the root command and sets flags appropriately. diff --git a/internal/pkg/print/markdown/document/document.go b/internal/pkg/print/markdown/document/document.go index 9d9697b..4a1681f 100644 --- a/internal/pkg/print/markdown/document/document.go +++ b/internal/pkg/print/markdown/document/document.go @@ -77,7 +77,7 @@ func printFencedCodeBlock(code string) string { func printInput(buffer *bytes.Buffer, input doc.Input, settings *settings.Settings) { buffer.WriteString("\n") - buffer.WriteString(fmt.Sprintf("### %s\n\n", markdown.SanitizeName(input.Name, settings))) + buffer.WriteString(fmt.Sprintf("%s %s\n\n", markdown.GenerateIndentation(1, settings), markdown.SanitizeName(input.Name, settings))) buffer.WriteString(fmt.Sprintf("Description: %s\n\n", markdown.SanitizeDescription(input.Description, settings))) buffer.WriteString(fmt.Sprintf("Type: `%s`\n", input.Type)) @@ -89,7 +89,7 @@ func printInput(buffer *bytes.Buffer, input doc.Input, settings *settings.Settin func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Settings) { if settings.ShowRequired { - buffer.WriteString("## Required Inputs\n\n") + buffer.WriteString(fmt.Sprintf("%s Required Inputs\n\n", markdown.GenerateIndentation(0, settings))) buffer.WriteString("The following input variables are required:\n") for _, input := range inputs { @@ -99,7 +99,7 @@ func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Se } buffer.WriteString("\n") - buffer.WriteString("## Optional Inputs\n\n") + buffer.WriteString(fmt.Sprintf("%s Optional Inputs\n\n", markdown.GenerateIndentation(0, settings))) buffer.WriteString("The following input variables are optional (have default values):\n") for _, input := range inputs { @@ -108,7 +108,7 @@ func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Se } } } else { - buffer.WriteString("## Inputs\n\n") + buffer.WriteString(fmt.Sprintf("%s Inputs\n\n", markdown.GenerateIndentation(0, settings))) buffer.WriteString("The following input variables are supported:\n") for _, input := range inputs { @@ -118,12 +118,12 @@ func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Se } func printOutputs(buffer *bytes.Buffer, outputs []doc.Output, settings *settings.Settings) { - buffer.WriteString("## Outputs\n\n") + buffer.WriteString(fmt.Sprintf("%s Outputs\n\n", markdown.GenerateIndentation(0, settings))) buffer.WriteString("The following outputs are exported:\n") for _, output := range outputs { buffer.WriteString("\n") - buffer.WriteString(fmt.Sprintf("### %s\n\n", markdown.SanitizeName(output.Name, settings))) + buffer.WriteString(fmt.Sprintf("%s %s\n\n", markdown.GenerateIndentation(1, settings), markdown.SanitizeName(output.Name, settings))) buffer.WriteString(fmt.Sprintf("Description: %s\n", markdown.SanitizeDescription(output.Description, settings))) } } diff --git a/internal/pkg/print/markdown/document/document_test.go b/internal/pkg/print/markdown/document/document_test.go index 8597881..18b3e0c 100644 --- a/internal/pkg/print/markdown/document/document_test.go +++ b/internal/pkg/print/markdown/document/document_test.go @@ -128,3 +128,63 @@ func TestPrintWithEscapeName(t *testing.T) { assert.Equal(t, expected, actual) } + +func TestPrintWithIndentationBellowAllowed(t *testing.T) { + doc := doc.TestDoc(t, "../..") + + var settings = &_settings.Settings{ + MarkdownIndent: 0, + } + + actual, err := document.Print(doc, settings) + if err != nil { + t.Fatal(err) + } + + expected, err := print.ReadGoldenFile("document-WithIndentationBellowAllowed") + if err != nil { + t.Fatal(err) + } + + assert.Equal(t, expected, actual) +} + +func TestPrintWithIndentationAboveAllowed(t *testing.T) { + doc := doc.TestDoc(t, "../..") + + var settings = &_settings.Settings{ + MarkdownIndent: 10, + } + + actual, err := document.Print(doc, settings) + if err != nil { + t.Fatal(err) + } + + expected, err := print.ReadGoldenFile("document-WithIndentationAboveAllowed") + if err != nil { + t.Fatal(err) + } + + assert.Equal(t, expected, actual) +} + +func TestPrintWithIndentationOfFour(t *testing.T) { + doc := doc.TestDoc(t, "../..") + + var settings = &_settings.Settings{ + MarkdownIndent: 4, + } + + actual, err := document.Print(doc, settings) + if err != nil { + t.Fatal(err) + } + + expected, err := print.ReadGoldenFile("document-WithIndentationOfFour") + if err != nil { + t.Fatal(err) + } + + assert.Equal(t, expected, actual) +} diff --git a/internal/pkg/print/markdown/document/testdata/document-WithIndentationAboveAllowed.golden b/internal/pkg/print/markdown/document/testdata/document-WithIndentationAboveAllowed.golden new file mode 100644 index 0000000..3c992db --- /dev/null +++ b/internal/pkg/print/markdown/document/testdata/document-WithIndentationAboveAllowed.golden @@ -0,0 +1,132 @@ +Usage: + +module "foo" { + 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" + } +} + +## Inputs + +The following input variables are supported: + +### unquoted + +Description: + +Type: `string` + +Default: n/a + +### string-3 + +Description: + +Type: `string` + +Default: `""` + +### string-2 + +Description: It's string number two. + +Type: `string` + +Default: n/a + +### string-1 + +Description: It's string number one. + +Type: `string` + +Default: `"bar"` + +### map-3 + +Description: + +Type: `map` + +Default: `` + +### map-2 + +Description: It's map number two. + +Type: `map` + +Default: n/a + +### map-1 + +Description: It's map number one. + +Type: `map` + +Default: `` + +### list-3 + +Description: + +Type: `list` + +Default: `` + +### list-2 + +Description: It's list number two. + +Type: `list` + +Default: n/a + +### list-1 + +Description: It's list number one. + +Type: `list` + +Default: `` + +### input_with_underscores + +Description: A variable with underscores. + +Type: `string` + +Default: n/a + +### input-with-pipe + +Description: It includes v1 \| v2 \| v3 + +Type: `string` + +Default: `"v1"` + +## Outputs + +The following outputs are exported: + +### unquoted + +Description: It's unquoted output. + +### output-2 + +Description: It's output number two. + +### output-1 + +Description: It's output number one. diff --git a/internal/pkg/print/markdown/document/testdata/document-WithIndentationBellowAllowed.golden b/internal/pkg/print/markdown/document/testdata/document-WithIndentationBellowAllowed.golden new file mode 100644 index 0000000..3c992db --- /dev/null +++ b/internal/pkg/print/markdown/document/testdata/document-WithIndentationBellowAllowed.golden @@ -0,0 +1,132 @@ +Usage: + +module "foo" { + 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" + } +} + +## Inputs + +The following input variables are supported: + +### unquoted + +Description: + +Type: `string` + +Default: n/a + +### string-3 + +Description: + +Type: `string` + +Default: `""` + +### string-2 + +Description: It's string number two. + +Type: `string` + +Default: n/a + +### string-1 + +Description: It's string number one. + +Type: `string` + +Default: `"bar"` + +### map-3 + +Description: + +Type: `map` + +Default: `` + +### map-2 + +Description: It's map number two. + +Type: `map` + +Default: n/a + +### map-1 + +Description: It's map number one. + +Type: `map` + +Default: `` + +### list-3 + +Description: + +Type: `list` + +Default: `` + +### list-2 + +Description: It's list number two. + +Type: `list` + +Default: n/a + +### list-1 + +Description: It's list number one. + +Type: `list` + +Default: `` + +### input_with_underscores + +Description: A variable with underscores. + +Type: `string` + +Default: n/a + +### input-with-pipe + +Description: It includes v1 \| v2 \| v3 + +Type: `string` + +Default: `"v1"` + +## Outputs + +The following outputs are exported: + +### unquoted + +Description: It's unquoted output. + +### output-2 + +Description: It's output number two. + +### output-1 + +Description: It's output number one. diff --git a/internal/pkg/print/markdown/document/testdata/document-WithIndentationOfFour.golden b/internal/pkg/print/markdown/document/testdata/document-WithIndentationOfFour.golden new file mode 100644 index 0000000..cb1531d --- /dev/null +++ b/internal/pkg/print/markdown/document/testdata/document-WithIndentationOfFour.golden @@ -0,0 +1,132 @@ +Usage: + +module "foo" { + 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" + } +} + +#### Inputs + +The following input variables are supported: + +##### unquoted + +Description: + +Type: `string` + +Default: n/a + +##### string-3 + +Description: + +Type: `string` + +Default: `""` + +##### string-2 + +Description: It's string number two. + +Type: `string` + +Default: n/a + +##### string-1 + +Description: It's string number one. + +Type: `string` + +Default: `"bar"` + +##### map-3 + +Description: + +Type: `map` + +Default: `` + +##### map-2 + +Description: It's map number two. + +Type: `map` + +Default: n/a + +##### map-1 + +Description: It's map number one. + +Type: `map` + +Default: `` + +##### list-3 + +Description: + +Type: `list` + +Default: `` + +##### list-2 + +Description: It's list number two. + +Type: `list` + +Default: n/a + +##### list-1 + +Description: It's list number one. + +Type: `list` + +Default: `` + +##### input_with_underscores + +Description: A variable with underscores. + +Type: `string` + +Default: n/a + +##### input-with-pipe + +Description: It includes v1 \| v2 \| v3 + +Type: `string` + +Default: `"v1"` + +#### Outputs + +The following outputs are exported: + +##### unquoted + +Description: It's unquoted output. + +##### output-2 + +Description: It's output number two. + +##### output-1 + +Description: It's output number one. diff --git a/internal/pkg/print/markdown/markdown.go b/internal/pkg/print/markdown/markdown.go index 4c5503e..0458a52 100644 --- a/internal/pkg/print/markdown/markdown.go +++ b/internal/pkg/print/markdown/markdown.go @@ -80,3 +80,19 @@ func Sanitize(markdown string) string { return result } + +// GenerateIndentation generates indentation of Markdown headers +// with base level of provided 'settings.MarkdownIndent' plus any +// extra level needed for subsection (e.g. 'Required Inputs' which +// is a subsection of 'Inputs' section) +func GenerateIndentation(extra int, settings *settings.Settings) string { + var base = settings.MarkdownIndent + if base < 1 || base > 5 { + base = 2 + } + var indent string + for i := 0; i < base+extra; i++ { + indent += "#" + } + return indent +} diff --git a/internal/pkg/print/markdown/table/table.go b/internal/pkg/print/markdown/table/table.go index 5858673..a06d0fb 100644 --- a/internal/pkg/print/markdown/table/table.go +++ b/internal/pkg/print/markdown/table/table.go @@ -60,7 +60,7 @@ func printComment(buffer *bytes.Buffer, comment string, settings *settings.Setti } func printInputs(buffer *bytes.Buffer, inputs []doc.Input, settings *settings.Settings) { - buffer.WriteString("## Inputs\n\n") + buffer.WriteString(fmt.Sprintf("%s Inputs\n\n", markdown.GenerateIndentation(0, settings))) buffer.WriteString("| Name | Description | Type | Default |") if settings.ShowRequired { @@ -102,7 +102,7 @@ func printIsInputRequired(input *doc.Input) string { } func printOutputs(buffer *bytes.Buffer, outputs []doc.Output, settings *settings.Settings) { - buffer.WriteString("## Outputs\n\n") + buffer.WriteString(fmt.Sprintf("%s Outputs\n\n", markdown.GenerateIndentation(0, settings))) buffer.WriteString("| Name | Description |\n") buffer.WriteString("|------|-------------|\n") diff --git a/internal/pkg/print/markdown/table/table_test.go b/internal/pkg/print/markdown/table/table_test.go index f7075de..082adcb 100644 --- a/internal/pkg/print/markdown/table/table_test.go +++ b/internal/pkg/print/markdown/table/table_test.go @@ -128,3 +128,63 @@ func TestPrintWithEscapeName(t *testing.T) { assert.Equal(t, expected, actual) } + +func TestPrintWithIndentationBellowAllowed(t *testing.T) { + doc := doc.TestDoc(t, "../..") + + var settings = &_settings.Settings{ + MarkdownIndent: 0, + } + + actual, err := table.Print(doc, settings) + if err != nil { + t.Fatal(err) + } + + expected, err := print.ReadGoldenFile("table-WithIndentationBellowAllowed") + if err != nil { + t.Fatal(err) + } + + assert.Equal(t, expected, actual) +} + +func TestPrintWithIndentationAboveAllowed(t *testing.T) { + doc := doc.TestDoc(t, "../..") + + var settings = &_settings.Settings{ + MarkdownIndent: 10, + } + + actual, err := table.Print(doc, settings) + if err != nil { + t.Fatal(err) + } + + expected, err := print.ReadGoldenFile("table-WithIndentationAboveAllowed") + if err != nil { + t.Fatal(err) + } + + assert.Equal(t, expected, actual) +} + +func TestPrintWithIndentationOfFour(t *testing.T) { + doc := doc.TestDoc(t, "../..") + + var settings = &_settings.Settings{ + MarkdownIndent: 4, + } + + actual, err := table.Print(doc, settings) + if err != nil { + t.Fatal(err) + } + + expected, err := print.ReadGoldenFile("table-WithIndentationOfFour") + if err != nil { + t.Fatal(err) + } + + assert.Equal(t, expected, actual) +} diff --git a/internal/pkg/print/markdown/table/testdata/table-WithIndentationAboveAllowed.golden b/internal/pkg/print/markdown/table/testdata/table-WithIndentationAboveAllowed.golden new file mode 100644 index 0000000..f5b4c0b --- /dev/null +++ b/internal/pkg/print/markdown/table/testdata/table-WithIndentationAboveAllowed.golden @@ -0,0 +1,41 @@ +Usage: + +module "foo" { + 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" + } +} + +## Inputs + +| Name | Description | Type | Default | +|------|-------------|:----:|:-----:| +| unquoted | | string | n/a | +| string-3 | | string | `""` | +| string-2 | It's string number two. | string | n/a | +| string-1 | It's string number one. | string | `"bar"` | +| map-3 | | map | `` | +| map-2 | It's map number two. | map | n/a | +| map-1 | It's map number one. | map | `` | +| list-3 | | list | `` | +| list-2 | It's list number two. | list | n/a | +| list-1 | It's list number one. | list | `` | +| input_with_underscores | A variable with underscores. | string | n/a | +| input-with-pipe | It includes v1 \| v2 \| v3 | string | `"v1"` | + +## Outputs + +| Name | Description | +|------|-------------| +| unquoted | It's unquoted output. | +| output-2 | It's output number two. | +| output-1 | It's output number one. | diff --git a/internal/pkg/print/markdown/table/testdata/table-WithIndentationBellowAllowed.golden b/internal/pkg/print/markdown/table/testdata/table-WithIndentationBellowAllowed.golden new file mode 100644 index 0000000..f5b4c0b --- /dev/null +++ b/internal/pkg/print/markdown/table/testdata/table-WithIndentationBellowAllowed.golden @@ -0,0 +1,41 @@ +Usage: + +module "foo" { + 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" + } +} + +## Inputs + +| Name | Description | Type | Default | +|------|-------------|:----:|:-----:| +| unquoted | | string | n/a | +| string-3 | | string | `""` | +| string-2 | It's string number two. | string | n/a | +| string-1 | It's string number one. | string | `"bar"` | +| map-3 | | map | `` | +| map-2 | It's map number two. | map | n/a | +| map-1 | It's map number one. | map | `` | +| list-3 | | list | `` | +| list-2 | It's list number two. | list | n/a | +| list-1 | It's list number one. | list | `` | +| input_with_underscores | A variable with underscores. | string | n/a | +| input-with-pipe | It includes v1 \| v2 \| v3 | string | `"v1"` | + +## Outputs + +| Name | Description | +|------|-------------| +| unquoted | It's unquoted output. | +| output-2 | It's output number two. | +| output-1 | It's output number one. | diff --git a/internal/pkg/print/markdown/table/testdata/table-WithIndentationOfFour.golden b/internal/pkg/print/markdown/table/testdata/table-WithIndentationOfFour.golden new file mode 100644 index 0000000..6c0c647 --- /dev/null +++ b/internal/pkg/print/markdown/table/testdata/table-WithIndentationOfFour.golden @@ -0,0 +1,41 @@ +Usage: + +module "foo" { + 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" + } +} + +#### Inputs + +| Name | Description | Type | Default | +|------|-------------|:----:|:-----:| +| unquoted | | string | n/a | +| string-3 | | string | `""` | +| string-2 | It's string number two. | string | n/a | +| string-1 | It's string number one. | string | `"bar"` | +| map-3 | | map | `` | +| map-2 | It's map number two. | map | n/a | +| map-1 | It's map number one. | map | `` | +| list-3 | | list | `` | +| list-2 | It's list number two. | list | n/a | +| list-1 | It's list number one. | list | `` | +| input_with_underscores | A variable with underscores. | string | n/a | +| input-with-pipe | It includes v1 \| v2 \| v3 | string | `"v1"` | + +#### Outputs + +| Name | Description | +|------|-------------| +| unquoted | It's unquoted output. | +| output-2 | It's output number two. | +| output-1 | It's output number one. | diff --git a/internal/pkg/settings/settings.go b/internal/pkg/settings/settings.go index fd8f377..9a315d5 100644 --- a/internal/pkg/settings/settings.go +++ b/internal/pkg/settings/settings.go @@ -10,6 +10,10 @@ type Settings struct { // scope: Markdown EscapeMarkdown bool + // MarkdownIndent control the indentation of Markdown headers [available: 1, 2, 3, 4, 5] (default: 2) + // scope: Markdown + MarkdownIndent int + // ShowRequired show "Required" column when generating Markdown (default: true) // scope: Markdown ShowRequired bool @@ -28,6 +32,7 @@ func NewSettings() *Settings { return &Settings{ AggregateTypeDefaults: false, EscapeMarkdown: true, + MarkdownIndent: 2, ShowRequired: true, SortByName: true, SortInputsByRequired: false,