feat(docs): Include Description and UsageText in docs output (#1287)

Include Description as part of the DESCRIPTION section, and put UsageText (if it is non-zero) into the Usage subsection.

docs_test.go

@@ -110,6 +110,7 @@ Should be a part of the same code block
 		}},
 	}}
 	app.UsageText = "app [first_arg] [second_arg]"
+	app.Description = `Description of the application.`
 	app.Usage = "Some app"
 	app.Authors = []*Author{
 		{Name: "Harrison", Email: "harrison@lolwut.com"},
@@ -178,6 +179,19 @@ func TestToMarkdownNoAuthors(t *testing.T) {
 	expectFileContent(t, "testdata/expected-doc-no-authors.md", res)
 }
 
+func TestToMarkdownNoUsageText(t *testing.T) {
+	// Given
+	app := testApp()
+	app.UsageText = ""
+
+	// When
+	res, err := app.ToMarkdown()
+
+	// Then
+	expect(t, err, nil)
+	expectFileContent(t, "testdata/expected-doc-no-usagetext.md", res)
+}
+
 func TestToMan(t *testing.T) {
 	// Given
 	app := testApp()

template.go

@@ -86,16 +86,18 @@ var MarkdownDocTemplate = `% {{ .App.Name }} {{ .SectionNum }}
 {{ if .SynopsisArgs }}
 ` + "```" + `
 {{ range $v := .SynopsisArgs }}{{ $v }}{{ end }}` + "```" + `
-{{ end }}{{ if .App.UsageText }}
+{{ end }}{{ if .App.Description }}
 # DESCRIPTION
 
-{{ .App.UsageText }}
+{{ .App.Description }}
 {{ end }}
 **Usage**:
 
-` + "```" + `
+` + "```" + `{{ if .App.UsageText }}
+{{ .App.UsageText }}
+{{ else }}
 {{ .App.Name }} [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
-` + "```" + `
+{{ end }}` + "```" + `
 {{ if .GlobalArgs }}
 # GLOBAL OPTIONS
 {{ range $v := .GlobalArgs }}

testdata/expected-doc-full.man

@@ -24,7 +24,7 @@ greet
 
 .SH DESCRIPTION
 .PP
-app [first\_arg] [second\_arg]
+Description of the application.
 
 .PP
 \fBUsage\fP:
@@ -33,7 +33,7 @@ app [first\_arg] [second\_arg]
 .RS
 
 .nf
-greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
+app [first\_arg] [second\_arg]
 
 .fi
 .RE

testdata/expected-doc-full.md

@@ -16,12 +16,12 @@ greet
 
 # DESCRIPTION
 
-app [first_arg] [second_arg]
+Description of the application.
 
 **Usage**:
 
 ```
-greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
+app [first_arg] [second_arg]
 ```
 
 # GLOBAL OPTIONS

testdata/expected-doc-no-authors.md

@@ -16,12 +16,12 @@ greet
 
 # DESCRIPTION
 
-app [first_arg] [second_arg]
+Description of the application.
 
 **Usage**:
 
 ```
-greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
+app [first_arg] [second_arg]
 ```
 
 # GLOBAL OPTIONS

testdata/expected-doc-no-commands.md

@@ -16,12 +16,12 @@ greet
 
 # DESCRIPTION
 
-app [first_arg] [second_arg]
+Description of the application.
 
 **Usage**:
 
 ```
-greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
+app [first_arg] [second_arg]
 ```
 
 # GLOBAL OPTIONS

testdata/expected-doc-no-flags.md

@@ -10,12 +10,12 @@ greet
 
 # DESCRIPTION
 
-app [first_arg] [second_arg]
+Description of the application.
 
 **Usage**:
 
 ```
-greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
+app [first_arg] [second_arg]
 ```
 
 # COMMANDS

testdata/expected-doc-no-usagetext.md

@@ -0,0 +1,86 @@
+% greet 8
+
+# NAME
+
+greet - Some app
+
+# SYNOPSIS
+
+greet
+
+```
+[--another-flag|-b]
+[--flag|--fl|-f]=[value]
+[--socket|-s]=[value]
+```
+
+# DESCRIPTION
+
+Description of the application.
+
+**Usage**:
+
+```
+greet [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
+```
+
+# GLOBAL OPTIONS
+
+**--another-flag, -b**: another usage text
+
+**--flag, --fl, -f**="": 
+
+**--socket, -s**="": some 'usage' text (default: value)
+
+
+# COMMANDS
+
+## config, c
+
+another usage test
+
+**--another-flag, -b**: another usage text
+
+**--flag, --fl, -f**="": 
+
+### sub-config, s, ss
+
+another usage test
+
+**--sub-command-flag, -s**: some usage text
+
+**--sub-flag, --sub-fl, -s**="": 
+
+## info, i, in
+
+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'
+
+    ```
+    func() { ... }
+    ```
+
+    Should be a part of the same code block
+
+**--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