feat(docs): add UsageText to docs output for markdown and man page ge…

…neration

docs.go

@@ -59,15 +59,16 @@ func prepareCommands(commands []*Command, level int) []string {
 		if command.Hidden {
 			continue
 		}
-		usage := ""
-		if command.Usage != "" {
-			usage = command.Usage
-		}
 
-		prepared := fmt.Sprintf("%s %s\n\n%s\n",
+		usageText := prepareUsageText(command)
+
+		usage := prepareUsage(command, usageText)
+
+		prepared := fmt.Sprintf("%s %s\n\n%s%s",
 			strings.Repeat("#", level+2),
 			strings.Join(command.Names(), ", "),
 			usage,
+			usageText,
 		)
 
 		flags := prepareArgsWithValues(command.Flags)
@@ -146,3 +147,35 @@ func flagDetails(flag DocGenerationFlag) string {
 	}
 	return ": " + description
 }
+
+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)
+		}
+	}
+	return usageText
+}
+
+func prepareUsage(command *Command, usageText string) string {
+	usage := ""
+	if command.Usage != "" {
+		usage = fmt.Sprintf("%s\n", command.Usage)
+	}
+
+	// Add a newline to the Usage IFF there is a UsageText
+	if usageText != "" && usage != "" {
+		usage = fmt.Sprintf("%s\n", usage)
+	}
+
+	return usage
+}

docs_test.go

@@ -66,6 +66,41 @@ func testApp() *App {
 	}, {
 		Name:   "hidden-command",
 		Hidden: true,
+	}, {
+		Aliases: []string{"u"},
+		Flags: []Flag{
+			&StringFlag{
+				Name:      "flag",
+				Aliases:   []string{"fl", "f"},
+				TakesFile: true,
+			},
+			&BoolFlag{
+				Name:    "another-flag",
+				Aliases: []string{"b"},
+				Usage:   "another usage text",
+			},
+		},
+		Name:  "usage",
+		Usage: "standard usage text",
+		UsageText: `
+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'
+`,
+		Subcommands: []*Command{{
+			Aliases: []string{"su"},
+			Flags: []Flag{
+				&BoolFlag{
+					Name:    "sub-command-flag",
+					Aliases: []string{"s"},
+					Usage:   "some usage text",
+				},
+			},
+			Name:      "sub-usage",
+			Usage:     "standard usage text",
+			UsageText: "Single line of UsageText",
+		}},
 	}}
 	app.UsageText = "app [first_arg] [second_arg]"
 	app.Usage = "Some app"

testdata/expected-doc-full.man

@@ -75,4 +75,40 @@ another usage test
 .PP
 retrieve generic information
 
-.SH some\-command
+.SH some\-command
+.SH usage, u
+.PP
+standard usage text
+
+.PP
+.RS
+
+.nf
+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'
+
+.fi
+.RE
+
+.PP
+\fB\-\-another\-flag, \-b\fP: another usage text
+
+.PP
+\fB\-\-flag, \-\-fl, \-f\fP="":
+
+.SS sub\-usage, su
+.PP
+standard usage text
+
+.PP
+.RS
+
+.PP
+Single line of UsageText
+
+.RE
+
+.PP
+\fB\-\-sub\-command\-flag, \-s\fP: some usage text

testdata/expected-doc-full.md

@@ -58,3 +58,25 @@ retrieve generic information
 ## some-command
 
 
+## usage, u
+
+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'
+```
+
+**--another-flag, -b**: another usage text
+
+**--flag, --fl, -f**="": 
+
+### sub-usage, su
+
+standard usage text
+
+>Single line of UsageText
+
+**--sub-command-flag, -s**: some usage text

testdata/expected-doc-no-authors.md

@@ -58,3 +58,25 @@ retrieve generic information
 ## some-command
 
 
+## usage, u
+
+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'
+```
+
+**--another-flag, -b**: another usage text
+
+**--flag, --fl, -f**="": 
+
+### sub-usage, su
+
+standard usage text
+
+>Single line of UsageText
+
+**--sub-command-flag, -s**: some usage text

testdata/expected-doc-no-flags.md

@@ -43,3 +43,25 @@ retrieve generic information
 ## some-command
 
 
+## usage, u
+
+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'
+```
+
+**--another-flag, -b**: another usage text
+
+**--flag, --fl, -f**="": 
+
+### sub-usage, su
+
+standard usage text
+
+>Single line of UsageText
+
+**--sub-command-flag, -s**: some usage text

testdata/expected-fish-full.fish

@@ -2,7 +2,7 @@
 
 function __fish_greet_no_subcommand --description 'Test if there has been any subcommand yet'
     for i in (commandline -opc)
-        if contains -- $i config c sub-config s ss info i in some-command
+        if contains -- $i config c sub-config s ss info i in some-command usage u sub-usage su
             return 1
         end
     end
@@ -27,3 +27,10 @@ complete -c greet -n '__fish_seen_subcommand_from info i in' -f -l help -s h -d
 complete -r -c greet -n '__fish_greet_no_subcommand' -a 'info i in' -d 'retrieve generic information'
 complete -c greet -n '__fish_seen_subcommand_from some-command' -f -l help -s h -d 'show help'
 complete -r -c greet -n '__fish_greet_no_subcommand' -a 'some-command'
+complete -c greet -n '__fish_seen_subcommand_from usage u' -f -l help -s h -d 'show help'
+complete -r -c greet -n '__fish_greet_no_subcommand' -a 'usage u' -d 'standard usage text'
+complete -c greet -n '__fish_seen_subcommand_from usage u' -l flag -s fl -s f -r
+complete -c greet -n '__fish_seen_subcommand_from usage u' -f -l another-flag -s b -d 'another usage text'
+complete -c greet -n '__fish_seen_subcommand_from sub-usage su' -f -l help -s h -d 'show help'
+complete -r -c greet -n '__fish_seen_subcommand_from usage u' -a 'sub-usage su' -d 'standard usage text'
+complete -c greet -n '__fish_seen_subcommand_from sub-usage su' -f -l sub-command-flag -s s -d 'some usage text'