Add documentation for Breakdown Chart (#1000)

* Begin breakdown chart documentation
* Fix generator build failure
* Add in breakdown chart graphics
* Add breakdown chart documentation and move cast files

docs/input/assets/casts/breakdown-chart-plain.cast

@@ -0,0 +1,3 @@
+{"version": 2, "width": 122, "height": 5, "title": "breakdown-chart (plain)", "env": {"TERM": "Spectre.Console"}}
+[0, "o", "\u001B[31m\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u001B[0m\u001B[34m\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u001B[0m\u001B[32m\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u001B[0m\u001B[37m\u2588\u2588\u001B[0m\u001B[37m\u2588\u2588\u001B[0m\r\n\u001B[31m\u25A0\u001B[0m SCSS \u001B[37m80\u001B[0m    \u001B[34m\u25A0\u001B[0m HTML \u001B[37m28.3\u001B[0m     \u001B[32m\u25A0\u001B[0m C# \u001B[37m22.6\u001B[0m    \u001B[37m\u25A0\u001B[0m JavaScript \u001B[37m6\u001B[0m    \r\n\u001B[37m\u25A0\u001B[0m Ruby \u001B[37m6\u001B[0m     \u001B[36m\u25A0\u001B[0m Shell \u001B[37m0.1\u001B[0m                                    \r\n"]
+

docs/input/assets/casts/breakdown-chart-rich.cast

@@ -0,0 +1,3 @@
+{"version": 2, "width": 122, "height": 5, "title": "breakdown-chart (rich)", "env": {"TERM": "Spectre.Console"}}
+[0, "o", "\u001B[38;5;9m\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u001B[0m\u001B[38;5;12m\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u001B[0m\u001B[38;5;2m\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u001B[0m\u001B[38;5;11m\u2588\u2588\u001B[0m\u001B[38;5;119m\u2588\u2588\u001B[0m\r\n\u001B[38;5;9m\u25A0\u001B[0m SCSS \u001B[38;5;8m80\u001B[0m    \u001B[38;5;12m\u25A0\u001B[0m HTML \u001B[38;5;8m28.3\u001B[0m     \u001B[38;5;2m\u25A0\u001B[0m C# \u001B[38;5;8m22.6\u001B[0m    \u001B[38;5;11m\u25A0\u001B[0m JavaScript \u001B[38;5;8m6\u001B[0m    \r\n\u001B[38;5;119m\u25A0\u001B[0m Ruby \u001B[38;5;8m6\u001B[0m     \u001B[38;5;14m\u25A0\u001B[0m Shell \u001B[38;5;8m0.1\u001B[0m                                    \r\n"]
+

docs/input/widgets/barchart.md

@@ -13,7 +13,6 @@ Use `BarChart` to render bar charts to the console.
 
 <?# AsciiCast cast="bar-chart" /?>
 
-
 ## Usage
 
 ### Basic usage

docs/input/widgets/breakdownchart.md

@@ -0,0 +1,134 @@
+Title: Breakdown Chart
+Order: 25
+Description: "Use **BreakdownChart** to render breakdown charts to the console."
+Highlights:
+    - Custom colors
+    - Labels
+    - Use your own data with a converter.
+Reference: T:Spectre.Console.BreakdownChart
+
+---
+
+Use `BreakdownChart` to render breakdown charts to the console.
+
+<?# AsciiCast cast="breakdown-chart" /?>
+
+## Usage
+
+### Basic usage
+
+```csharp
+AnsiConsole.Write(new BreakdownChart()
+    .Width(60)
+    // Add item is in the order of label, value, then color.
+    .AddItem("SCSS", 80, Color.Red)
+    .AddItem("HTML", 28.3, Color.Blue)
+    .AddItem("C#", 22.6, Color.Green)
+    .AddItem("JavaScript", 6, Color.Yellow)
+    .AddItem("Ruby", 6, Color.LightGreen)
+    .AddItem("Shell", 0.1, Color.Aqua));
+```
+
+### Additional Styling
+
+```csharp
+// Render chart at full width of console.
+AnsiConsole.Write(new BreakdownChart()
+    .FullSize()
+    .AddItem("SCSS", 80, Color.Red)
+    .AddItem("HTML", 28.3, Color.Blue)
+    .AddItem("C#", 22.6, Color.Green)
+    .AddItem("JavaScript", 6, Color.Yellow)
+    .AddItem("Ruby", 6, Color.LightGreen)
+    .AddItem("Shell", 0.1, Color.Aqua));
+```
+
+```csharp
+// Show percentage signs after the values in the chart.
+AnsiConsole.Write(new BreakdownChart()
+    .ShowPercentage()
+    .AddItem("SCSS", 80, Color.Red)
+    .AddItem("HTML", 28.3, Color.Blue)
+    .AddItem("C#", 22.6, Color.Green)
+    .AddItem("JavaScript", 6, Color.Yellow)
+    .AddItem("Ruby", 6, Color.LightGreen)
+    .AddItem("Shell", 0.1, Color.Aqua));
+```
+
+```csharp
+// Hide tags displaying in the chart altogether.
+AnsiConsole.Write(new BreakdownChart()
+    .HideTag()
+    .AddItem("SCSS", 80, Color.Red)
+    .AddItem("HTML", 28.3, Color.Blue)
+    .AddItem("C#", 22.6, Color.Green)
+    .AddItem("JavaScript", 6, Color.Yellow)
+    .AddItem("Ruby", 6, Color.LightGreen)
+    .AddItem("Shell", 0.1, Color.Aqua));
+```
+
+```csharp
+// Hide the values next to the tag from displaying in the chart.
+AnsiConsole.Write(new BreakdownChart()
+    .HideTagValues()
+    .AddItem("SCSS", 80, Color.Red)
+    .AddItem("HTML", 28.3, Color.Blue)
+    .AddItem("C#", 22.6, Color.Green)
+    .AddItem("JavaScript", 6, Color.Yellow)
+    .AddItem("Ruby", 6, Color.LightGreen)
+    .AddItem("Shell", 0.1, Color.Aqua));
+```
+
+### Additional Functionality
+
+#### Add items with converter
+
+```csharp
+// Create a list of fruits with their colors
+var items = new List<(string Label, double Value, Color color)>
+{
+    ("Apple", 12, Color.Green),
+    ("Orange", 54, Color.Orange1),
+    ("Banana", 33, Color.Yellow),
+};
+
+// Render the chart
+AnsiConsole.Write(new BreakdownChart()
+    .FullSize()
+    .ShowPercentage()
+    .AddItems(items, (item) => new BreakdownChartItem(
+        item.Label, item.Value, item.color)));
+```
+
+#### Add items implementing IBreakdownChartItem
+
+```csharp
+// Declare Fruit that implements IBreakdownChartItem
+public sealed class Fruit : IBreakdownChartItem
+{
+    public string Label { get; set; }
+    public double Value { get; set; }
+    public Color Color { get; set; }
+
+    public Fruit(string label, double value, Color color)
+    {
+        Label = label;
+        Value = value;
+        Color = color;
+    }
+}
+
+// Create a list of fruits
+var items = new List<Fruit>
+{
+    new Fruit("Apple", 12, Color.Green),
+    new Fruit("Orange", 54, Color.Orange1),
+    new Fruit("Banana", 33, Color.Yellow),
+}
+
+// Render chart
+AnsiConsole.Write(new BreakdownChart()
+.Width(60)
+.AddItem(new Fruit("Mango", 3, Color.Orange4))
+.AddItems(items));
+```

resources/scripts/Generator/Commands/AsciiCast/Samples/BreakdownChartSample.cs

@@ -0,0 +1,21 @@
+using Spectre.Console;
+
+namespace Generator.Commands.Samples
+{
+    internal class BreakdownChartSample : BaseSample
+    {
+        public override (int Cols, int Rows) ConsoleSize => (base.ConsoleSize.Cols, 5);
+
+        public override void Run(IAnsiConsole console)
+        {
+            console.Write(new BreakdownChart()
+                .Width(60)
+                .AddItem("SCSS", 80, Color.Red)
+                .AddItem("HTML", 28.3, Color.Blue)
+                .AddItem("C#", 22.6, Color.Green)
+                .AddItem("JavaScript", 6, Color.Yellow)
+                .AddItem("Ruby", 6, Color.LightGreen)
+                .AddItem("Shell", 0.1, Color.Aqua));
+        }
+    }
+}

resources/scripts/Generator/Generator.csproj

@@ -51,6 +51,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Spectre.Console.Cli\Spectre.Console.Cli.csproj" />
     <ProjectReference Include="..\..\..\src\Spectre.Console.ImageSharp\Spectre.Console.ImageSharp.csproj" />
     <ProjectReference Include="..\..\..\src\Spectre.Console\Spectre.Console.csproj" />
   </ItemGroup>

resources/scripts/Generator/Generator.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 16
+# Visual Studio Version 17
-VisualStudioVersion = 16.0.30320.27
+VisualStudioVersion = 17.3.32922.545
 MinimumVisualStudioVersion = 15.0.26124.0
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Generator", "Generator.csproj", "{5668D267-53E3-4B99-97AE-59AA597D22ED}"
 EndProject
@@ -11,6 +11,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Spectre.Console.ImageSharp"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Library", "Library", "{CFE7445D-F971-429D-B6E6-9E68456AE00F}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Spectre.Console.Cli", "..\..\..\src\Spectre.Console.Cli\Spectre.Console.Cli.csproj", "{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -57,6 +59,18 @@ Global
 		{112A37CB-1EFE-4A90-BD5B-5437038BE276}.Release|x64.Build.0 = Release|Any CPU
 		{112A37CB-1EFE-4A90-BD5B-5437038BE276}.Release|x86.ActiveCfg = Release|Any CPU
 		{112A37CB-1EFE-4A90-BD5B-5437038BE276}.Release|x86.Build.0 = Release|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Debug|x64.Build.0 = Debug|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Debug|x86.Build.0 = Debug|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Release|x64.ActiveCfg = Release|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Release|x64.Build.0 = Release|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Release|x86.ActiveCfg = Release|Any CPU
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -64,6 +78,7 @@ Global
 	GlobalSection(NestedProjects) = preSolution
 		{F75B882A-06DB-426B-9580-A7302D32E684} = {CFE7445D-F971-429D-B6E6-9E68456AE00F}
 		{112A37CB-1EFE-4A90-BD5B-5437038BE276} = {CFE7445D-F971-429D-B6E6-9E68456AE00F}
+		{18A3F32D-FECD-463B-A194-6EE74EA9E5EC} = {CFE7445D-F971-429D-B6E6-9E68456AE00F}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {5F37FDE3-D591-4D43-8DDE-2ED6BAB0A7B4}