Allow custom help providers (#1259)

Allow custom help providers

* Version option will show in help even with a default command

* Reserve `-v` and `--version` as special Spectre.Console command line arguments (nb. breaking change for Spectre.Console users who have a default command with a settings class that uses either of these switches).

* Help writer correctly determines if trailing commands exist and whether to display them as optional or mandatory in the usage statement.

* Ability to control the number of indirect commands to display in the help text when the command itself doesn't have any examples of its own. Defaults to 5 (for backward compatibility) but can be set to any integer or zero to disable completely.

* Significant increase in unit test coverage for the help writer.

* Minor grammatical improvements to website documentation.

test/Spectre.Console.Cli.Tests/Expectations/Help/ArgumentOrder.Output.verified.txt

@@ -9,4 +9,5 @@ ARGUMENTS:
     [QUX]
 
 OPTIONS:
-    -h, --help    Prints help information
+    -h, --help       Prints help information
+    -v, --version    Prints version information

test/Spectre.Console.Cli.Tests/Expectations/Help/Branch_Called_Without_Help.Output.verified.txt

@@ -0,0 +1,18 @@
+DESCRIPTION:
+Contains settings for a cat.
+
+USAGE:
+    myapp cat [LEGS] [OPTIONS] <COMMAND>
+
+ARGUMENTS:
+    [LEGS]    The number of legs
+
+OPTIONS:
+                             DEFAULT
+    -h, --help                          Prints help information
+    -a, --alive                         Indicates whether or not the animal is alive
+    -n, --name <VALUE>
+        --agility <VALUE>    10         The agility between 0 and 100
+
+COMMANDS:
+    lion <TEETH>    The lion command

test/Spectre.Console.Cli.Tests/Expectations/Help/Branch_Default_Greeter.Output.verified.txt

@@ -0,0 +1,11 @@
+USAGE:
+    myapp branch [GREETING] [OPTIONS] [COMMAND]
+
+ARGUMENTS:
+    [GREETING]
+
+OPTIONS:
+    -h, --help    Prints help information
+
+COMMANDS:
+    greeter

test/Spectre.Console.Cli.Tests/Expectations/Help/Branch_Examples.Output.verified.txt

@@ -0,0 +1,30 @@
+DESCRIPTION:
+The animal command.
+
+USAGE:
+    myapp animal [LEGS] [OPTIONS] <COMMAND>
+
+EXAMPLES:
+    myapp animal dog --name Rufus --age 12 --good-boy
+    myapp animal dog --name Luna
+    myapp animal dog --name Charlie
+    myapp animal dog --name Bella
+    myapp animal dog --name Daisy
+    myapp animal dog --name Milo
+    myapp animal horse --name Brutus
+    myapp animal horse --name Sugar --IsAlive false
+    myapp animal horse --name Cash
+    myapp animal horse --name Dakota
+    myapp animal horse --name Cisco
+    myapp animal horse --name Spirit
+
+ARGUMENTS:
+    [LEGS]    The number of legs
+
+OPTIONS:
+    -h, --help     Prints help information
+    -a, --alive    Indicates whether or not the animal is alive
+
+COMMANDS:
+    dog <AGE>    The dog command
+    horse        The horse command

test/Spectre.Console.Cli.Tests/Expectations/Help/CommandExamples.Output.verified.txt

@@ -1,19 +0,0 @@
-DESCRIPTION:
-The animal command.
-
-USAGE:
-    myapp animal [LEGS] [OPTIONS] <COMMAND>
-
-EXAMPLES:
-    myapp animal --help
-
-ARGUMENTS:
-    [LEGS]    The number of legs
-
-OPTIONS:
-    -h, --help     Prints help information
-    -a, --alive    Indicates whether or not the animal is alive
-
-COMMANDS:
-    dog <AGE>    The dog command
-    horse        The horse command

test/Spectre.Console.Cli.Tests/Expectations/Help/Custom_Help_Configured_By_Instance.Output.verified.txt

@@ -0,0 +1,15 @@
+--------------------------------------
+---      CUSTOM HELP PROVIDER      ---
+--------------------------------------
+
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    dog <AGE>    The dog command
+
+Version 1.0

test/Spectre.Console.Cli.Tests/Expectations/Help/Custom_Help_Configured_By_Type.Output.verified.txt

@@ -0,0 +1 @@
+Help has moved online. Please see: http://www.example.com

test/Spectre.Console.Cli.Tests/Expectations/Help/Custom_Help_Registered_By_Instance.Output.verified.txt

@@ -0,0 +1,15 @@
+--------------------------------------
+---      CUSTOM HELP PROVIDER      ---
+--------------------------------------
+
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    dog <AGE>    The dog command
+
+Version 1.0

test/Spectre.Console.Cli.Tests/Expectations/Help/Custom_Help_Registered_By_Type.Output.verified.txt

@@ -0,0 +1 @@
+Help has moved online. Please see: http://www.example.com

test/Spectre.Console.Cli.Tests/Expectations/Help/Default.Output.verified.txt

@@ -1,4 +1,4 @@
-DESCRIPTION:
+DESCRIPTION:
 The lion command.
 
 USAGE:
@@ -10,7 +10,8 @@ ARGUMENTS:
 
 OPTIONS:
                              DEFAULT
-    -h, --help                                   Prints help information
+    -h, --help                                   Prints help information
+    -v, --version                                Prints version information
     -a, --alive                                  Indicates whether or not the animal is alive
     -n, --name <VALUE>
         --agility <VALUE>    10                  The agility between 0 and 100

test/Spectre.Console.Cli.Tests/Expectations/Help/DefaultExamples.Output.verified.txt

@@ -1,21 +0,0 @@
-DESCRIPTION:
-The lion command.
-
-USAGE:
-    myapp <TEETH> [LEGS] [OPTIONS]
-
-EXAMPLES:
-    myapp 12 -c 3
-
-ARGUMENTS:
-    <TEETH>    The number of teeth the lion has
-    [LEGS]     The number of legs
-
-OPTIONS:
-                             DEFAULT
-    -h, --help                                   Prints help information
-    -a, --alive                                  Indicates whether or not the animal is alive
-    -n, --name <VALUE>
-        --agility <VALUE>    10                  The agility between 0 and 100
-    -c <CHILDREN>                                The number of children the lion has
-    -d <DAY>                 Monday, Thursday    The days the lion goes hunting

test/Spectre.Console.Cli.Tests/Expectations/Help/Default_Custom_Help_Provider.Output.verified.txt

@@ -0,0 +1,15 @@
+--------------------------------------
+---      CUSTOM HELP PROVIDER      ---
+--------------------------------------
+
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    dog <AGE>    The dog command
+
+Version 1.0

test/Spectre.Console.Cli.Tests/Expectations/Help/Default_Examples.Output.verified.txt

@@ -0,0 +1,24 @@
+DESCRIPTION:
+The dog command.
+
+USAGE:
+    myapp <AGE> [LEGS] [OPTIONS]
+
+EXAMPLES:
+    myapp --name Rufus --age 12 --good-boy
+    myapp --name Luna
+    myapp --name Charlie
+    myapp --name Bella
+    myapp --name Daisy
+    myapp --name Milo
+
+ARGUMENTS:
+    <AGE>
+    [LEGS]    The number of legs
+
+OPTIONS:
+    -h, --help            Prints help information
+    -v, --version         Prints version information
+    -a, --alive           Indicates whether or not the animal is alive
+    -n, --name <VALUE>
+    -g, --good-boy

test/Spectre.Console.Cli.Tests/Expectations/Help/Default_Without_Args.Output.verified.txt

@@ -1,4 +1,4 @@
-DESCRIPTION:
+DESCRIPTION:
 The lion command.
 
 USAGE:
@@ -10,7 +10,8 @@ ARGUMENTS:
 
 OPTIONS:
                              DEFAULT
-    -h, --help                                   Prints help information
+    -h, --help                                   Prints help information
+    -v, --version                                Prints version information
     -a, --alive                                  Indicates whether or not the animal is alive
     -n, --name <VALUE>
         --agility <VALUE>    10                  The agility between 0 and 100

test/Spectre.Console.Cli.Tests/Expectations/Help/Default_Without_Args_Additional.Output.verified.txt

@@ -1,8 +1,8 @@
-DESCRIPTION:
+DESCRIPTION:
 The lion command.
 
 USAGE:
-    myapp <TEETH> [LEGS] [OPTIONS]
+    myapp <TEETH> [LEGS] [OPTIONS] [COMMAND]
 
 ARGUMENTS:
     <TEETH>    The number of teeth the lion has
@@ -10,7 +10,8 @@ ARGUMENTS:
 
 OPTIONS:
                              DEFAULT
-    -h, --help                                   Prints help information
+    -h, --help                                   Prints help information
+    -v, --version                                Prints version information
     -a, --alive                                  Indicates whether or not the animal is alive
     -n, --name <VALUE>
         --agility <VALUE>    10                  The agility between 0 and 100

test/Spectre.Console.Cli.Tests/Expectations/Help/Hidden_Command_Options.Output.verified.txt

@@ -5,5 +5,6 @@ ARGUMENTS:
     <FOO>    Dummy argument FOO
 
 OPTIONS:
-    -h, --help    Prints help information
-        --baz     Dummy option BAZ
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+        --baz        Dummy option BAZ

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples.Output.verified.txt

@@ -0,0 +1,24 @@
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+EXAMPLES:
+    myapp dog --name Rufus --age 12 --good-boy
+    myapp dog --name Luna
+    myapp dog --name Charlie
+    myapp dog --name Bella
+    myapp dog --name Daisy
+    myapp dog --name Milo
+    myapp horse --name Brutus
+    myapp horse --name Sugar --IsAlive false
+    myapp horse --name Cash
+    myapp horse --name Dakota
+    myapp horse --name Cisco
+    myapp horse --name Spirit
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    dog <AGE>    The dog command
+    horse        The horse command

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples_Children.Output.verified.txt

@@ -3,7 +3,10 @@ USAGE:
 
 EXAMPLES:
     myapp dog --name Rufus --age 12 --good-boy
-    myapp horse --name Brutus
+    myapp dog --name Luna
+    myapp dog --name Charlie
+    myapp dog --name Bella
+    myapp dog --name Daisy
 
 OPTIONS:
     -h, --help       Prints help information

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples_Children_Eight.Output.verified.txt

@@ -0,0 +1,20 @@
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+EXAMPLES:
+    myapp dog --name Rufus --age 12 --good-boy
+    myapp dog --name Luna
+    myapp dog --name Charlie
+    myapp dog --name Bella
+    myapp dog --name Daisy
+    myapp dog --name Milo
+    myapp horse --name Brutus
+    myapp horse --name Sugar --IsAlive false
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    dog <AGE>    The dog command
+    horse        The horse command

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples_Children_None.Output.verified.txt

@@ -1,14 +1,10 @@
-USAGE:
-    myapp [OPTIONS] <COMMAND>
-
-EXAMPLES:
-    myapp dog --name Rufus --age 12 --good-boy
-    myapp horse --name Brutus
-
-OPTIONS:
-    -h, --help       Prints help information
-    -v, --version    Prints version information
-
-COMMANDS:
-    dog <AGE>    The dog command
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    dog <AGE>    The dog command
     horse        The horse command

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples_Children_Twelve.Output.verified.txt

@@ -0,0 +1,24 @@
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+EXAMPLES:
+    myapp dog --name Rufus --age 12 --good-boy
+    myapp dog --name Luna
+    myapp dog --name Charlie
+    myapp dog --name Bella
+    myapp dog --name Daisy
+    myapp dog --name Milo
+    myapp horse --name Brutus
+    myapp horse --name Sugar --IsAlive false
+    myapp horse --name Cash
+    myapp horse --name Dakota
+    myapp horse --name Cisco
+    myapp horse --name Spirit
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    dog <AGE>    The dog command
+    horse        The horse command

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples_Leafs.Output.verified.txt

@@ -3,7 +3,10 @@ USAGE:
 
 EXAMPLES:
     myapp animal dog --name Rufus --age 12 --good-boy
-    myapp animal horse --name Brutus
+    myapp animal dog --name Luna
+    myapp animal dog --name Charlie
+    myapp animal dog --name Bella
+    myapp animal dog --name Daisy
 
 OPTIONS:
     -h, --help       Prints help information

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples_Leafs_Eight.Output.verified.txt

@@ -0,0 +1,19 @@
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+EXAMPLES:
+    myapp animal dog --name Rufus --age 12 --good-boy
+    myapp animal dog --name Luna
+    myapp animal dog --name Charlie
+    myapp animal dog --name Bella
+    myapp animal dog --name Daisy
+    myapp animal dog --name Milo
+    myapp animal horse --name Brutus
+    myapp animal horse --name Sugar --IsAlive false
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    animal    The animal command

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples_Leafs_None.Output.verified.txt

@@ -0,0 +1,9 @@
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    animal    The animal command

test/Spectre.Console.Cli.Tests/Expectations/Help/Root_Examples_Leafs_Twelve.Output.verified.txt

@@ -0,0 +1,23 @@
+USAGE:
+    myapp [OPTIONS] <COMMAND>
+
+EXAMPLES:
+    myapp animal dog --name Rufus --age 12 --good-boy
+    myapp animal dog --name Luna
+    myapp animal dog --name Charlie
+    myapp animal dog --name Bella
+    myapp animal dog --name Daisy
+    myapp animal dog --name Milo
+    myapp animal horse --name Brutus
+    myapp animal horse --name Sugar --IsAlive false
+    myapp animal horse --name Cash
+    myapp animal horse --name Dakota
+    myapp animal horse --name Cisco
+    myapp animal horse --name Spirit
+
+OPTIONS:
+    -h, --help       Prints help information
+    -v, --version    Prints version information
+
+COMMANDS:
+    animal    The animal command