From 364d9c38c5c4298b045d002dbe686f3116079255 Mon Sep 17 00:00:00 2001 From: Derek Smith Date: Sun, 15 Nov 2020 22:38:30 -0600 Subject: [PATCH] feat(docs): updated tests, DRYd up code, cleaned up string logic --- docs.go | 39 +++++----- docs_test.go | 113 ++++++++++++++++++++++++++++ testdata/expected-doc-full.man | 6 ++ testdata/expected-doc-full.md | 16 ++-- testdata/expected-doc-no-authors.md | 16 ++-- testdata/expected-doc-no-flags.md | 16 ++-- 6 files changed, 171 insertions(+), 35 deletions(-) diff --git a/docs.go b/docs.go index d35af9cefa..6caa359400 100644 --- a/docs.go +++ b/docs.go @@ -149,32 +149,37 @@ func flagDetails(flag DocGenerationFlag) string { } func prepareUsageText(command *Command) string { - usageText := "" - if command.UsageText != "" { - // Remove leading and trailing newlines - preparedUsageText := strings.TrimSuffix(command.UsageText, "\n") - preparedUsageText = strings.TrimPrefix(preparedUsageText, "\n") - - if strings.Contains(preparedUsageText, "\n") { - // Format multi-line string as a code block - usageText = fmt.Sprintf("```\n%s\n```\n", preparedUsageText) - } else { - // Style a single line as a note - usageText = fmt.Sprintf(">%s\n", preparedUsageText) + if command.UsageText == "" { + return "" + } + + // Remove leading and trailing newlines + preparedUsageText := strings.Trim(command.UsageText, "\n") + + var usageText string + if strings.Contains(preparedUsageText, "\n") { + // Format multi-line string as a code block using the 4 space schema to allow for embedded markdown such + // that it will not break the continuous code block. + for _, ln := range strings.Split(preparedUsageText, "\n") { + usageText += fmt.Sprintf(" %s\n", ln) } + } else { + // Style a single line as a note + usageText = fmt.Sprintf(">%s\n", preparedUsageText) } + return usageText } func prepareUsage(command *Command, usageText string) string { - usage := "" - if command.Usage != "" { - usage = fmt.Sprintf("%s\n", command.Usage) + if command.Usage == "" { + return "" } + usage := command.Usage + "\n" // Add a newline to the Usage IFF there is a UsageText - if usageText != "" && usage != "" { - usage = fmt.Sprintf("%s\n", usage) + if usageText != "" { + usage += "\n" } return usage diff --git a/docs_test.go b/docs_test.go index 400dc66a3e..5e90394407 100644 --- a/docs_test.go +++ b/docs_test.go @@ -87,6 +87,12 @@ Usage for the usage text - formatted: Based on the specified ConfigMap and summon secrets.yml - list: Inspect the environment for a specific process running on a Pod - for_effect: Compare 'namespace' environment with 'local' + +` + "```" + ` +func() { ... } +` + "```" + ` + +Should be a part of the same code block `, Subcommands: []*Command{{ Aliases: []string{"su"}, @@ -182,3 +188,110 @@ func TestToMan(t *testing.T) { expect(t, err, nil) expectFileContent(t, "testdata/expected-doc-full.man", res) } + +func Test_prepareUsageText(t *testing.T) { + t.Run("no UsageText provided", func(t *testing.T) { + // Given + cmd := Command{} + + // When + res := prepareUsageText(&cmd) + + // Then + expect(t, res, "") + }) + + t.Run("single line UsageText", func(t *testing.T) { + // Given + cmd := Command{UsageText: "Single line usage text"} + + // When + res := prepareUsageText(&cmd) + + // Then + expect(t, res, ">Single line usage text\n") + }) + + t.Run("multiline UsageText", func(t *testing.T) { + // Given + cmd := Command{ + UsageText: ` +Usage for the usage text +- Should be a part of the same code block +`, + } + + // When + res := prepareUsageText(&cmd) + + // Then + test := ` Usage for the usage text + - Should be a part of the same code block +` + expect(t, res, test) + }) + + t.Run("multiline UsageText has formatted embedded markdown", func(t *testing.T) { + // Given + cmd := Command{ + UsageText: ` +Usage for the usage text + +` + "```" + ` +func() { ... } +` + "```" + ` + +Should be a part of the same code block +`, + } + + // When + res := prepareUsageText(&cmd) + + // Then + test := ` Usage for the usage text + + ` + "```" + ` + func() { ... } + ` + "```" + ` + + Should be a part of the same code block +` + expect(t, res, test) + }) +} + +func Test_prepareUsage(t *testing.T) { + t.Run("no Usage provided", func(t *testing.T) { + // Given + cmd := Command{} + + // When + res := prepareUsage(&cmd, "") + + // Then + expect(t, res, "") + }) + + t.Run("simple Usage", func(t *testing.T) { + // Given + cmd := Command{Usage: "simple usage text"} + + // When + res := prepareUsage(&cmd, "") + + // Then + expect(t, res, cmd.Usage + "\n") + }) + + t.Run("simple Usage with UsageText", func(t *testing.T) { + // Given + cmd := Command{Usage: "simple usage text"} + + // When + res := prepareUsage(&cmd, "a non-empty string") + + // Then + expect(t, res, cmd.Usage + "\n\n") + }) +} \ No newline at end of file diff --git a/testdata/expected-doc-full.man b/testdata/expected-doc-full.man index 0b96cd0cb4..3ac35539cb 100644 --- a/testdata/expected-doc-full.man +++ b/testdata/expected-doc-full.man @@ -89,6 +89,12 @@ Usage for the usage text \- list: Inspect the environment for a specific process running on a Pod \- for\_effect: Compare 'namespace' environment with 'local' +``` +func() { ... } +``` + +Should be a part of the same code block + .fi .RE diff --git a/testdata/expected-doc-full.md b/testdata/expected-doc-full.md index c2246c987b..7b8c0d7e9e 100644 --- a/testdata/expected-doc-full.md +++ b/testdata/expected-doc-full.md @@ -62,12 +62,16 @@ retrieve generic information standard usage text -``` -Usage for the usage text -- formatted: Based on the specified ConfigMap and summon secrets.yml -- list: Inspect the environment for a specific process running on a Pod -- for_effect: Compare 'namespace' environment with 'local' -``` + Usage for the usage text + - formatted: Based on the specified ConfigMap and summon secrets.yml + - list: Inspect the environment for a specific process running on a Pod + - for_effect: Compare 'namespace' environment with 'local' + + ``` + func() { ... } + ``` + + Should be a part of the same code block **--another-flag, -b**: another usage text diff --git a/testdata/expected-doc-no-authors.md b/testdata/expected-doc-no-authors.md index c2246c987b..7b8c0d7e9e 100644 --- a/testdata/expected-doc-no-authors.md +++ b/testdata/expected-doc-no-authors.md @@ -62,12 +62,16 @@ retrieve generic information standard usage text -``` -Usage for the usage text -- formatted: Based on the specified ConfigMap and summon secrets.yml -- list: Inspect the environment for a specific process running on a Pod -- for_effect: Compare 'namespace' environment with 'local' -``` + Usage for the usage text + - formatted: Based on the specified ConfigMap and summon secrets.yml + - list: Inspect the environment for a specific process running on a Pod + - for_effect: Compare 'namespace' environment with 'local' + + ``` + func() { ... } + ``` + + Should be a part of the same code block **--another-flag, -b**: another usage text diff --git a/testdata/expected-doc-no-flags.md b/testdata/expected-doc-no-flags.md index d656d1faab..ebd0416ecd 100644 --- a/testdata/expected-doc-no-flags.md +++ b/testdata/expected-doc-no-flags.md @@ -47,12 +47,16 @@ retrieve generic information standard usage text -``` -Usage for the usage text -- formatted: Based on the specified ConfigMap and summon secrets.yml -- list: Inspect the environment for a specific process running on a Pod -- for_effect: Compare 'namespace' environment with 'local' -``` + Usage for the usage text + - formatted: Based on the specified ConfigMap and summon secrets.yml + - list: Inspect the environment for a specific process running on a Pod + - for_effect: Compare 'namespace' environment with 'local' + + ``` + func() { ... } + ``` + + Should be a part of the same code block **--another-flag, -b**: another usage text