feat(docs): add UsageText to docs output for markdown and man page generation (#1171)

* feat(docs): add UsageText to docs output for markdown and man page generation

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

* fix(lint): fixed go1.15 lint errors

testdata/expected-doc-full.man

@@ -75,4 +75,46 @@ 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'
+
+```
+func() { ... }
+```
+
+Should be a part of the same code block
+
+.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,29 @@ 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

testdata/expected-doc-no-authors.md

@@ -58,3 +58,29 @@ 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

testdata/expected-doc-no-flags.md

@@ -43,3 +43,29 @@ 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

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'