Improve Console report format documentation with examples, screenshots, and automated regeneration scripts

docs/input/assets/scripts/console-examples/.config/dotnet-tools.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "cake.tool": {
+      "version": "5.0.0",
+      "commands": [
+        "dotnet-cake"
+      ]
+    }
+  }
+}

docs/input/assets/scripts/console-examples/.gitignore

@@ -0,0 +1,19 @@
+# Tool artifacts
+tools/
+.dotnet/
+
+# Build artifacts
+bin/
+obj/
+
+# NuGet packages
+*.nupkg
+packages/
+
+# Cake Build
+.cake/
+
+# Sample files for testing (not part of the real project structure)
+src/
+docs/
+myfile.txt

docs/input/assets/scripts/console-examples/README.md

@@ -0,0 +1,124 @@
+# Console Report Format Example Scripts
+
+This directory contains scripts used to generate the console output screenshots shown in the Console report format documentation.
+
+## Purpose
+
+These scripts allow reproducing the console output examples to:
+- Regenerate screenshots when the addin is updated
+- Test different console formatting options
+- Validate console output behavior
+
+## Scripts
+
+- `generate-default.cake` - Default console output settings with individual diagnostics
+- `generate-grouped.cake` - Console output grouped by rule
+- `generate-summaries.cake` - Console output with provider and priority summaries
+- `generate-combined.cake` - Console output with all features enabled
+- `sample-issues.json` - Sample issues data used by all scripts
+- `generate-screenshot.sh` - Helper script to generate PNG screenshots from console output
+- `run-examples.sh` - Script to generate all screenshots at once
+
+## Prerequisites
+
+Before running the scripts, ensure you have:
+
+1. **Built the NuGet packages** (required for the scripts to work):
+   ```bash
+   cd /path/to/Cake.Issues
+   ./build.sh --target=Create-NuGet-Packages
+   ```
+
+2. **Required tools installed**:
+   - `dotnet` (for running Cake scripts)
+   - `ansi2html` (for converting ANSI terminal output to HTML)
+   - `wkhtmltoimage` (for converting HTML to PNG images)
+
+   Install the Python tools:
+   ```bash
+   pip install ansi2html
+   sudo apt install wkhtmltopdf  # includes wkhtmltoimage
+   ```
+
+## Usage
+
+### Generate All Screenshots
+
+To regenerate all console output screenshots at once:
+
+```bash
+cd docs/input/assets/scripts/console-examples
+./run-examples.sh
+```
+
+This will generate all four PNG files in `docs/input/assets/images/console-examples/`:
+- `console-default.png`
+- `console-grouped.png`
+- `console-summaries.png`
+- `console-combined.png`
+
+### Generate Individual Screenshots
+
+To generate a specific screenshot:
+
+```bash
+cd docs/input/assets/scripts/console-examples
+./generate-screenshot.sh <script-name> <output-image-name>
+```
+
+Examples:
+```bash
+./generate-screenshot.sh generate-default.cake console-default.png
+./generate-screenshot.sh generate-grouped.cake console-grouped.png
+./generate-screenshot.sh generate-summaries.cake console-summaries.png
+./generate-screenshot.sh generate-combined.cake console-combined.png
+```
+
+### Run Scripts Without Screenshots
+
+To just run the examples and see the console output without generating images:
+
+```bash
+cd docs/input/assets/scripts/console-examples
+dotnet tool restore
+dotnet tool run dotnet-cake generate-default.cake --settings_skippackageversioncheck=true
+```
+
+## Screenshot Generation Process
+
+The screenshot generation works as follows:
+
+1. **Run Cake script** - Execute the console report script and capture all output including ANSI color codes
+2. **Convert ANSI to HTML** - Use `ansi2html` to convert terminal colors to HTML with CSS
+3. **Style HTML** - Apply additional CSS styling for a clean terminal appearance
+4. **Generate PNG** - Use `wkhtmltoimage` to convert the styled HTML to a PNG image
+5. **Save to docs** - Place the generated PNG in the documentation assets directory
+
+## Sample Data
+
+The `sample-issues.json` file contains realistic issue data representing:
+- MSBuild compiler warnings and suggestions
+- DupFinder duplicate code detection issues  
+- InspectCode style and best practice violations
+- markdownlint documentation issues
+- Custom script issues
+
+Supporting files (`src/ClassLibrary1/Class1.cs`, `docs/index.md`, `myfile.txt`) are included to ensure the issues reference existing files, which is required for the console diagnostics to display properly.
+
+## Example Output
+
+The scripts demonstrate four distinct console output modes:
+
+### 1. Default Settings
+Shows individual diagnostics for each issue with detailed file context and syntax highlighting.
+
+### 2. Grouped by Rule (`GroupByRule: true`)
+Groups issues with the same rule ID together, reducing redundancy and improving readability when multiple instances of the same issue exist.
+
+### 3. With Summary Tables (`ShowProviderSummary: true`, `ShowPrioritySummary: true`)
+Includes visual bar charts and detailed tables showing issue counts by provider and priority levels.
+
+### 4. Combined Features
+Demonstrates the most comprehensive output combining grouped diagnostics with summary tables.
+
+This produces output similar to what users would see in real projects, helping them choose the right console report configuration for their needs.

docs/input/assets/scripts/console-examples/generate-combined.cake

@@ -0,0 +1,43 @@
+#addin "Cake.Issues&prerelease"
+#addin "Cake.Issues.Reporting&prerelease"
+#addin "Cake.Issues.Reporting.Console&prerelease"
+
+//////////////////////////////////////////////////
+// ARGUMENTS
+//////////////////////////////////////////////////
+
+var target = Argument("target", "Default");
+
+//////////////////////////////////////////////////
+// TARGETS
+//////////////////////////////////////////////////
+
+Task("Print-Issues-Combined")
+    .Does(() =>
+{
+    Information("Running Console Report with All Features Enabled");
+
+    var issues = DeserializeIssuesFromJsonFile("sample-issues.json");
+    Information("Read {0} issues", issues.Count());
+
+    CreateIssueReport(
+        issues,
+        ConsoleIssueReportFormat(
+            new ConsoleIssueReportFormatSettings
+            {
+                GroupByRule = true,
+                ShowProviderSummary = true,
+                ShowPrioritySummary = true
+            }),
+        @".",
+        string.Empty);
+});
+
+Task("Default")
+    .IsDependentOn("Print-Issues-Combined");
+
+//////////////////////////////////////////////////
+// EXECUTION
+//////////////////////////////////////////////////
+
+RunTarget(target);

docs/input/assets/scripts/console-examples/generate-default.cake

@@ -0,0 +1,41 @@
+#addin "Cake.Issues&prerelease"
+#addin "Cake.Issues.Reporting&prerelease"
+#addin "Cake.Issues.Reporting.Console&prerelease"
+
+//////////////////////////////////////////////////
+// ARGUMENTS
+//////////////////////////////////////////////////
+
+var target = Argument("target", "Default");
+
+//////////////////////////////////////////////////
+// TARGETS
+//////////////////////////////////////////////////
+
+Task("Print-Issues-Default")
+    .Does(() =>
+{
+    Information("Running Console Report with Default Settings");
+
+    var issues = DeserializeIssuesFromJsonFile("sample-issues.json");
+    Information("Read {0} issues", issues.Count());
+
+    CreateIssueReport(
+        issues,
+        ConsoleIssueReportFormat(
+            new ConsoleIssueReportFormatSettings 
+            { 
+                ShowDiagnostics = true
+            }),
+        @".",
+        string.Empty);
+});
+
+Task("Default")
+    .IsDependentOn("Print-Issues-Default");
+
+//////////////////////////////////////////////////
+// EXECUTION
+//////////////////////////////////////////////////
+
+RunTarget(target);

docs/input/assets/scripts/console-examples/generate-grouped.cake

@@ -0,0 +1,41 @@
+#addin "Cake.Issues&prerelease"
+#addin "Cake.Issues.Reporting&prerelease"
+#addin "Cake.Issues.Reporting.Console&prerelease"
+
+//////////////////////////////////////////////////
+// ARGUMENTS
+//////////////////////////////////////////////////
+
+var target = Argument("target", "Default");
+
+//////////////////////////////////////////////////
+// TARGETS
+//////////////////////////////////////////////////
+
+Task("Print-Issues-Grouped")
+    .Does(() =>
+{
+    Information("Running Console Report with Grouped by Rule");
+
+    var issues = DeserializeIssuesFromJsonFile("sample-issues.json");
+    Information("Read {0} issues", issues.Count());
+
+    CreateIssueReport(
+        issues,
+        ConsoleIssueReportFormat(
+            new ConsoleIssueReportFormatSettings
+            {
+                GroupByRule = true
+            }),
+        @".",
+        string.Empty);
+});
+
+Task("Default")
+    .IsDependentOn("Print-Issues-Grouped");
+
+//////////////////////////////////////////////////
+// EXECUTION
+//////////////////////////////////////////////////
+
+RunTarget(target);

docs/input/assets/scripts/console-examples/generate-screenshot.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+# Script to generate console output and convert to PNG image
+# Usage: generate-screenshot.sh <script-name> <output-image-name>
+
+set -e
+
+SCRIPT_NAME="$1"
+IMAGE_NAME="$2"
+DOCS_IMAGE_DIR="../../images/console-examples"
+
+if [ -z "$SCRIPT_NAME" ] || [ -z "$IMAGE_NAME" ]; then
+    echo "Usage: $0 <script-name> <output-image-name>"
+    echo "Example: $0 generate-default.cake console-default.png"
+    exit 1
+fi
+
+echo "Generating console output for $SCRIPT_NAME..."
+
+# Create temp directory for output
+TEMP_DIR=$(mktemp -d)
+trap "rm -rf $TEMP_DIR" EXIT
+
+# Generate console output with ANSI colors
+script -q -c "dotnet tool run dotnet-cake $SCRIPT_NAME --settings_skippackageversioncheck=true 2>&1" "$TEMP_DIR/console-output.txt"
+
+# Convert ANSI to HTML
+ansi2html --scheme dracula < "$TEMP_DIR/console-output.txt" > "$TEMP_DIR/console-output.html"
+
+# Add custom CSS for better terminal appearance
+cat > "$TEMP_DIR/styled-console.html" << 'EOF'
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <style>
+        body {
+            background-color: #1e1e2e;
+            color: #cdd6f4;
+            font-family: 'Consolas', 'Monaco', 'Courier New', monospace;
+            font-size: 14px;
+            line-height: 1.2;
+            margin: 20px;
+            padding: 20px;
+            border-radius: 8px;
+            box-shadow: 0 4px 8px rgba(0, 0, 0, 0.3);
+        }
+        pre {
+            margin: 0;
+            padding: 0;
+            white-space: pre-wrap;
+            word-wrap: break-word;
+        }
+    </style>
+</head>
+<body>
+<pre>
+EOF
+
+# Extract the content between first and last "Script" lines and add to styled HTML
+sed -n '/Script started/,/Script done/p' "$TEMP_DIR/console-output.html" | \
+    sed '1d;$d' | \
+    sed 's/^[^>]*>//g' >> "$TEMP_DIR/styled-console.html"
+
+cat >> "$TEMP_DIR/styled-console.html" << 'EOF'
+</pre>
+</body>
+</html>
+EOF
+
+# Ensure docs image directory exists
+mkdir -p "$DOCS_IMAGE_DIR"
+
+# Convert HTML to PNG with specific dimensions and styling
+wkhtmltoimage \
+    --width 1200 \
+    --height 800 \
+    --quality 100 \
+    --format png \
+    --javascript-delay 1000 \
+    --no-stop-slow-scripts \
+    --enable-local-file-access \
+    "$TEMP_DIR/styled-console.html" \
+    "$DOCS_IMAGE_DIR/$IMAGE_NAME"
+
+echo "Screenshot saved to: $DOCS_IMAGE_DIR/$IMAGE_NAME"