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.

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