Adds documentation for analyzers

docs/input/analyzer/rules/RULE_TEMPLATE.md

@@ -0,0 +1,38 @@
+---
+Title: SpectreXxxx
+Description: Rule title
+Category: Usage
+Severity: Hidden, Info, Warning, or Error
+Excluded: true
+---
+
+## Cause
+
+A concise-as-possible description of when this rule is violated. If there's a lot to explain, begin with "A violation of this rule occurs when..."
+
+## Reason for rule
+
+Explain why the user should care about the violation.
+
+## How to fix violations
+
+To fix a violation of this rule, [describe how to fix a violation].
+
+## Examples
+
+### Violates
+
+Example(s) of code that violates the rule.
+
+### Does not violate
+
+Example(s) of code that does not violate the rule.
+
+## How to suppress violations
+
+**If the severity of your analyzer isn't _Warning_, delete this section.**
+
+```csharp
+#pragma warning disable Spectre1000 // <Rule name>
+#pragma warning restore Spectre1000 // <Rule name>
+```

docs/input/analyzer/rules/Spectre1021.md

@@ -0,0 +1,56 @@
+---
+Title: Spectre1021
+Description: Avoid prompting for input while a current renderable is running.
+Category: Usage
+Severity: Warning
+---
+
+## Cause
+
+A violation of this rule occurs when a AnsiConsole prompt is called within the context of an executing renderable e.g. `Progress`, `Status` and `Live`. Concurrent LiveRenderable are not supported and will cause issues when running simultaneously.
+
+## Reason for rule
+
+When LiveRenderable such as `Progress`, `Status` or `Live` are running they expect to be running exclusively. They rely on ANSI sequences to draw and keep the console experience consistent. Prompts also rely on ANSI sequences for their drawing. Simultaneous running can result in corrupt output.
+
+## How to fix violations
+
+Redesign logic to allow one LiveRenderable to complete before using a prompt or prompt before starting the operation. 
+
+## Examples
+
+### Violates
+
+```csharp
+AnsiConsole.Progress().Start(ctx =>
+{
+    // code to update progress bar
+    var answer = AnsiConsole.Confirm("Continue?");
+});
+```
+
+### Does not violate
+
+```csharp
+AnsiConsole.Progress().Start(ctx =>
+{
+    // code to update progress bar
+
+    // persist state to restart progress after asking question   
+});
+
+var answer = AnsiConsole.Confirm("Continue?");
+
+AnsiConsole.Progress().Start(ctx =>
+{
+    // apply persisted state
+    // code to update progress bar
+```
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable Spectre1021 // <Rule name>
+
+#pragma warning restore Spectre1021 // <Rule name>
+```

docs/input/analyzer/rules/_ViewStart.cshtml

@@ -0,0 +1,3 @@
+@{
+    Layout = @"_layout.cshtml";
+}

docs/input/analyzer/rules/_layout.cshtml

@@ -0,0 +1,10 @@
+@inherits StatiqRazorPage<IDocument>
+
+@{
+    Layout = @"/_layout.cshtml";
+}
+
+
+<p>@Document.GetString("Description")</p>
+
+@RenderBody()

docs/input/analyzer/rules/index.cshtml

@@ -0,0 +1,31 @@
+Title: Roslyn Analyzers
+Order: 20
+---
+
+<code>Spectre.Console.Analyzer</code> provides analyzers for common mistakes when using Spectre.Console. It can be installed via nuget
+
+<pre><code>nuget install Spectre.Console.Analyzer</code></pre>
+
+<h2>Supported Analyzers</h2>
+
+<table>
+    <thead>
+        <tr>
+            <th>Analyzer</th>
+            <th>Description</th>
+            <th>Category</th>
+            <th>Severity</th>
+        </tr>
+    </thead>
+    <tbody>
+    @foreach (IDocument child in OutputPages.GetChildrenOf(Document))
+    {
+        <tr>
+            <td>@Html.DocumentLink(child)</td>
+            <td>@child.GetString("Description")</td>
+            <td>@child.GetString("Category") </td>
+            <td>@child.GetString("Severity") </td>
+        </tr>
+    }
+    </tbody>
+</table>

docs/input/analyzer/rules/spectre1000.md

@@ -0,0 +1,27 @@
+---
+Title: Spectre1000
+Description: Use AnsiConsole instead of System.Console
+Category: Usage
+Severity: Warning
+---
+
+## Cause
+
+A violation of this rule occurs when `System.Console` is used for common methods exposed by Spectre.Console.
+
+## Reason for rule
+
+Methods implemented in Spectre.Console should be used over direct access to `System.Console` to allow for enhancements and
+features to be enabled.
+
+## How to fix violations
+
+To fix a violation of this rule, change from `System.Console` to `Spectre.Console.AnsiConsole`.
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable Spectre1000 // Use AnsiConsole instead of System.Console
+
+#pragma warning restore Spectre1000 // Use AnsiConsole instead of System.Console
+```

docs/input/analyzer/rules/spectre1010.md

@@ -0,0 +1,63 @@
+---
+Title: Spectre1010
+Description: Favor the use of the instance of AnsiConsole over the static helper
+Category: Usage
+Severity: Info
+---
+
+## Cause
+
+A violation of this rule occurs when the static helper `AnsiConsole` is used when a field or method parameter of type
+`IAnsiConsole` is available.
+
+## Reason for rule
+
+Use of `IAnsiConsole` improves testability of the code, and also allows upstream callers the ability to customize the console
+capabilities and features. When a field variable or parameter is available it should be used to ensure the code takes advantage
+of that configuration.
+
+## How to fix violations
+
+To fix a violation of this rule, change from `AnsiConsole` to the name of the local instance.
+
+## Examples
+
+### Violates
+
+```csharp
+class Example
+{
+    private IAnsiConsole _ansiConsole;
+
+    public Example(IAnsiConsole ansiConsole) 
+    {
+        _ansiConsole = ansiConsole;
+    }
+
+    public Run()
+    {
+        AnsiConsole.WriteLine("Running...");
+    }
+
+}
+```
+
+### Does not violate
+
+```csharp
+class Example
+{
+    private IAnsiConsole _ansiConsole;
+
+    public Example(IAnsiConsole ansiConsole) 
+    {
+        _ansiConsole = ansiConsole;
+    }
+
+    public Run()
+    {
+        _ansiConsole.WriteLine("Running...");
+    }
+
+}
+```

docs/input/analyzer/rules/spectre1020.md

@@ -0,0 +1,46 @@
+---
+Title: Spectre1020
+Description: Avoid calling other live renderables while a current renderable is running.
+Category: Usage
+Severity: Warning
+---
+
+## Cause
+
+A violation of this rule occurs when a child LiveRenderable i.e. `Progress`, `Status` and `Live` are called within the context of an executing renderable. Concurrent LiveRenderable are not supported and will cause issues when running simultaneously.
+
+## Reason for rule
+
+When LiveRenderable such as `Progress`, `Status` or `Live` are running they expect to be running exclusively. They rely on ANSI sequences to draw and keep the console experience consistent. With simultaneous calls both renderables compete with the console causing concurrent writes corrupting the output.
+
+## How to fix violations
+
+Redesign logic to allow one LiveRenderable to complete before starting a second renderable. 
+
+## Examples
+
+### Violates
+
+```csharp
+AnsiConsole.Progress().Start(ctx => {
+    AnsiConsole.Status().Start("Running status too...", statusCtx => {});
+});
+```
+
+### Does not violate
+
+```csharp
+AnsiConsole.Progress().Start(ctx => {
+    // run progress and complete tasks
+});
+
+AnsiConsole.Status().Start("Running status afterwards...", statusCtx => {});
+```
+
+## How to suppress violations
+
+```csharp
+#pragma warning disable Spectre1020 // <Rule name>
+
+#pragma warning restore Spectre1020 // <Rule name>
+```