Repository: spectreconsole/spectre.console

Issue:
Export for Documentation
I'm currently manually creating the documentation to put on my site for the CLI usage. Which gave me a thought...

Would it be possible to do some sort of export of the the documentation. 

If I have branch commands I have to go into each command and call `-h` to get the output for that command, then I use that to build the documentation on the site.

I have no idea how you would solve it nicely, maybe a nuget tool which analysis it and generates a .md file. 

Feel free to close this is my idea is stupid... 


Hints:
A little hidden gem of Spectre.Console.Cli is that you can export XML structure with a hidden command.
Try passing `cli xmldoc` to your application and it should give you the XML structure:

<img width="776" alt="image" src="https://user-images.githubusercontent.com/357872/208904802-44228d2a-1dd1-4cf7-b7a2-47d298ddce7f.png">

You can use this XML to generate documentation for your app.

Other than lacking Description and Examples, this is awesome!

`explain` is really nice for being able to view the branches and check that descriptions and examples have been written.
We could add description and examples to the xmldoc output.
I don't mind trying to do a PR next week if you can point me in the right direction. 
@phillip-haydon The command you would want to extend is the `XmlDocCommand` which can be found here: https://github.com/spectreconsole/spectre.console/blob/main/src/Spectre.Console.Cli/Internal/Commands/XmlDocCommand.cs
> I don't mind trying to do a PR next week if you can point me in the right direction.

Still interested in preparing a PR for this @phillip-haydon?   If so, I can make myself available to review with a view to merging.
Hey, would still love this, no time at the moment :(.

Patch:
diff --git a/src/Spectre.Console.Cli/Internal/Commands/XmlDocCommand.cs b/src/Spectre.Console.Cli/Internal/Commands/XmlDocCommand.cs
index 807251833..7b7592ca8 100644
--- a/src/Spectre.Console.Cli/Internal/Commands/XmlDocCommand.cs
+++ b/src/Spectre.Console.Cli/Internal/Commands/XmlDocCommand.cs
@@ -84,6 +84,13 @@ private static XmlNode CreateCommandNode(XmlDocument doc, CommandInfo command, b
 
         node.SetNullableAttribute("Settings", command.SettingsType?.FullName);
 
+        if (!string.IsNullOrWhiteSpace(command.Description))
+        {
+            var descriptionNode = doc.CreateElement("Description");
+            descriptionNode.InnerText = command.Description;
+            node.AppendChild(descriptionNode);
+        }
+
         // Parameters
         if (command.Parameters.Count > 0)
         {
@@ -103,6 +110,27 @@ private static XmlNode CreateCommandNode(XmlDocument doc, CommandInfo command, b
             node.AppendChild(CreateCommandNode(doc, childCommand));
         }
 
+        // Examples
+        if (command.Examples.Count > 0)
+        {
+            var exampleRootNode = doc.CreateElement("Examples");
+            foreach (var example in command.Examples.SelectMany(static x => x))
+            {
+                var exampleNode = CreateExampleNode(doc, example);
+                exampleRootNode.AppendChild(exampleNode);
+            }
+
+            node.AppendChild(exampleRootNode);
+        }
+
+        return node;
+    }
+
+    private static XmlNode CreateExampleNode(XmlDocument document, string example)
+    {
+        var node = document.CreateElement("Example");
+        node.SetAttribute("commandLine", example);
+
         return node;
     }
 


Test patch:
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_1.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_1.Output.verified.txt
index 998a89b3a..e92f683de 100644
--- a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_1.Output.verified.txt
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_1.Output.verified.txt
@@ -21,6 +21,7 @@
       </Parameters>
       <!--DOG-->
       <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+        <Description>The dog command.</Description>
         <Parameters>
           <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
           <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@@ -28,6 +29,7 @@
       </Command>
       <!--HORSE-->
       <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+        <Description>The horse command.</Description>
         <Parameters>
           <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
           <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_10.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_10.Output.verified.txt
new file mode 100644
index 000000000..2c89d04a7
--- /dev/null
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_10.Output.verified.txt
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Model>
+  <!--DOG-->
+  <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+    <Description>The dog command.</Description>
+    <Parameters>
+      <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
+        <Description>The number of legs.</Description>
+        <Validators>
+          <Validator ClrType="Spectre.Console.Tests.Data.EvenNumberValidatorAttribute" Message="Animals must have an even number of legs." />
+          <Validator ClrType="Spectre.Console.Tests.Data.PositiveNumberValidatorAttribute" Message="Number of legs must be greater than 0." />
+        </Validators>
+      </Argument>
+      <Argument Name="AGE" Position="1" Required="true" Kind="scalar" ClrType="System.Int32" />
+      <Option Short="a" Long="alive,not-dead" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean">
+        <Description>Indicates whether or not the animal is alive.</Description>
+      </Option>
+      <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
+      <Option Short="n,p" Long="name,pet-name" Value="VALUE" Required="false" Kind="scalar" ClrType="System.String" />
+    </Parameters>
+    <Examples>
+      <Example commandLine="dog -g" />
+      <Example commandLine="dog --good-boy" />
+    </Examples>
+  </Command>
+</Model>
\ No newline at end of file
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_2.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_2.Output.verified.txt
index 9f3463020..29098b822 100644
--- a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_2.Output.verified.txt
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_2.Output.verified.txt
@@ -2,6 +2,7 @@
 <Model>
   <!--DOG-->
   <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+    <Description>The dog command.</Description>
     <Parameters>
       <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
         <Description>The number of legs.</Description>
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_3.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_3.Output.verified.txt
index 6b1f90fba..ffb491802 100644
--- a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_3.Output.verified.txt
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_3.Output.verified.txt
@@ -16,6 +16,7 @@
     </Parameters>
     <!--DOG-->
     <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+      <Description>The dog command.</Description>
       <Parameters>
         <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
         <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@@ -24,6 +25,7 @@
     </Command>
     <!--HORSE-->
     <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+      <Description>The horse command.</Description>
       <Parameters>
         <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
         <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_4.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_4.Output.verified.txt
index 594918922..07b9dcd35 100644
--- a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_4.Output.verified.txt
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_4.Output.verified.txt
@@ -16,6 +16,7 @@
     </Parameters>
     <!--DOG-->
     <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+      <Description>The dog command.</Description>
       <Parameters>
         <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
         <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_6.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_6.Output.verified.txt
index 0907636ae..92b2aba93 100644
--- a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_6.Output.verified.txt
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_6.Output.verified.txt
@@ -2,6 +2,7 @@
 <Model>
   <!--DEFAULT COMMAND-->
   <Command Name="__default_command" IsBranch="false" IsDefault="true" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+    <Description>The dog command.</Description>
     <Parameters>
       <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
         <Description>The number of legs.</Description>
@@ -20,6 +21,7 @@
   </Command>
   <!--HORSE-->
   <Command Name="horse" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+    <Description>The horse command.</Description>
     <Parameters>
       <Argument Name="LEGS" Position="0" Required="false" Kind="scalar" ClrType="System.Int32">
         <Description>The number of legs.</Description>
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_7.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_7.Output.verified.txt
index 46ae6a82a..69699701d 100644
--- a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_7.Output.verified.txt
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_7.Output.verified.txt
@@ -21,6 +21,7 @@
       </Parameters>
       <!--__DEFAULT_COMMAND-->
       <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+        <Description>The horse command.</Description>
         <Parameters>
           <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
           <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_8.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_8.Output.verified.txt
index 3f836ae57..5ccfbd01a 100644
--- a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_8.Output.verified.txt
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_8.Output.verified.txt
@@ -16,6 +16,7 @@
     </Parameters>
     <!--DOG-->
     <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+      <Description>The dog command.</Description>
       <Parameters>
         <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
         <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@@ -24,6 +25,7 @@
     </Command>
     <!--__DEFAULT_COMMAND-->
     <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+      <Description>The horse command.</Description>
       <Parameters>
         <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
         <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />
diff --git a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_9.Output.verified.txt b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_9.Output.verified.txt
index 5549f5dcf..7c2396bb0 100644
--- a/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_9.Output.verified.txt
+++ b/test/Spectre.Console.Cli.Tests/Expectations/Xml/Test_9.Output.verified.txt
@@ -18,6 +18,7 @@
     </Parameters>
     <!--DOG-->
     <Command Name="dog" IsBranch="false" ClrType="Spectre.Console.Tests.Data.DogCommand" Settings="Spectre.Console.Tests.Data.DogSettings">
+      <Description>The dog command.</Description>
       <Parameters>
         <Argument Name="AGE" Position="0" Required="true" Kind="scalar" ClrType="System.Int32" />
         <Option Short="g" Long="good-boy" Value="NULL" Required="false" Kind="flag" ClrType="System.Boolean" />
@@ -26,6 +27,7 @@
     </Command>
     <!--__DEFAULT_COMMAND-->
     <Command Name="__default_command" IsBranch="false" ClrType="Spectre.Console.Tests.Data.HorseCommand" Settings="Spectre.Console.Tests.Data.HorseSettings">
+      <Description>The horse command.</Description>
       <Parameters>
         <Option Short="d" Long="day" Value="MON|TUE" Required="false" Kind="scalar" ClrType="System.DayOfWeek" />
         <Option Short="" Long="directory" Value="NULL" Required="false" Kind="scalar" ClrType="System.IO.DirectoryInfo" />
diff --git a/test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.Xml.cs b/test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.Xml.cs
index 1ed1b4152..8a6348b9e 100644
--- a/test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.Xml.cs
+++ b/test/Spectre.Console.Cli.Tests/Unit/CommandAppTests.Xml.cs
@@ -110,6 +110,26 @@ public Task Should_Dump_Correct_Model_For_Case_5()
             return Verifier.Verify(result.Output);
         }
 
+        [Fact]
+        [Expectation("Test_10")]
+        public Task Should_Dump_Correct_Model_For_Case_6()
+        {
+            // Given
+            var fixture = new CommandAppTester();
+            fixture.Configure(config =>
+            {
+                config.AddCommand<DogCommand>("dog")
+                    .WithExample("dog -g")
+                    .WithExample("dog --good-boy");
+            });
+
+            // When
+            var result = fixture.Run(Constants.XmlDocCommand);
+
+            // Then
+            return Verifier.Verify(result.Output);
+        }
+
         [Fact]
         [Expectation("Test_6")]
         public Task Should_Dump_Correct_Model_For_Model_With_Default_Command()