feat(docs): updated tests, DRYd up code, cleaned up string logic

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

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")
+	})
+}

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
 

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
 

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
 

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