Improve report & PR feature documentation (#861)

cake-contrib · Dec 28, 2024 · c86f258 · c86f258
1 parent 6a59e81
commit c86f258
Show file tree

Hide file tree

Showing 22 changed files with 154 additions and 63 deletions.
diff --git a/docs/docs/documentation/pull-request-systems/appveyor/examples/index.md b/docs/docs/documentation/pull-request-systems/appveyor/examples/index.md
@@ -1,8 +1,16 @@
 ---
 title: Examples
 description: Examples for using the Cake.Issues.PullRequests.AppVeyor addin.
+icon: material/test-tube
 ---
 
+<div class="grid cards" markdown>
+
+- [Writting Messages To AppVeyor](write-messages.md)
+- [GitHub PullRequest Integration](github-pullrequest-integration.md)
+
+</div>
+
 !!! info
     There's a [demo repository](https://github.com/pascalberger/Cake.Issues-Demo)
     available which you can fork and to which you can create pull requests to test the integration functionality.
diff --git a/docs/docs/documentation/pull-request-systems/appveyor/features.md b/docs/docs/documentation/pull-request-systems/appveyor/features.md
@@ -1,31 +1,30 @@
 ---
 title: Features
 description: Features of the Cake.Issues.PullRequests.AppVeyor addin.
+icon: material/creation-outline
 ---
 
-The [Cake.Issues.PullRequests.AppVeyor addin] reports issues as messages to AppVeyor builds.
+The [Cake.Issues.PullRequests.AppVeyor addin]{target="_blank"} reports issues as messages to AppVeyor builds.
 
 ![AppVeyor messages](appveyor-messages.png "AppVeyor messages")
 
 !!! info
-    There's a [demo repository] available which you can fork and to which you can create pull requests to test the integration functionality.
+    There's a [demo repository]{target="_blank"} available which you can fork and to which you can create pull requests to test the integration functionality.
 
 ## Basic features
 
-* Reports issues as messages to AppVeyor builds.
-* Messages can be written as comment to GitHub pull requests.
-  See [GitHub pull request integration] for an example.
+- [x] Reports issues as messages to AppVeyor builds.
+- [x] Messages can be written as comment to GitHub pull requests.
+      See [GitHub pull request integration] for an example.
 
 ## Supported capabilities
 
-The [Cake.Issues.PullRequests.AppVeyor addin] doesn't support any additional capabilities.
+The [Cake.Issues.PullRequests.AppVeyor addin]{target="_blank"} doesn't support any additional capabilities.
 
-|                  | Capability                     | Remarks                        |
-|------------------|--------------------------------|--------------------------------|
-|                  | Checking commit ID             |                                |
-|                  | Discussion threads             |                                |
-|                  | Filtering by modified files    |                                |
+- [ ] Checking commit ID
+- [ ] Discussion threads
+- [ ] Filtering by modified files
 
 [demo repository]: https://github.com/pascalberger/Cake.Issues-Demo
-[Cake.Issues.PullRequests.AppVeyor addin]: https://www.nuget.org/packages/Cake.Issues.PullRequests.AppVeyor
+[Cake.Issues.PullRequests.AppVeyor addin]: https://cakebuild.net/extensions/cake-issues-pullrequests-appveyor/
 [GitHub pull request integration]: ./examples/github-pullrequest-integration.md
diff --git a/docs/docs/documentation/pull-request-systems/appveyor/index.md b/docs/docs/documentation/pull-request-systems/appveyor/index.md
@@ -4,4 +4,11 @@ description: Support for AppVeyor.
 ---
 
 Support for AppVeyor is implemented in the
-[Cake.Issues.PullRequests.AppVeyor addin](https://www.nuget.org/packages/Cake.Issues.PullRequests.AppVeyor).
+[Cake.Issues.PullRequests.AppVeyor addin](https://cakebuild.net/extensions/cake-issues-pullrequests-appveyor/){target="_blank"}.
+
+<div class="grid cards" markdown>
+
+- :material-creation-outline: [Features](features.md)
+- :material-test-tube: [Examples](examples/index.md)
+
+</div>
diff --git a/docs/docs/documentation/pull-request-systems/azure-devops/examples/index.md b/docs/docs/documentation/pull-request-systems/azure-devops/examples/index.md
@@ -1,8 +1,17 @@
 ---
 title: Examples
 description: Examples for using the Cake.Issues.PullRequests.AzureDevOps addin.
+icon: material/test-tube
 ---
 
+<div class="grid cards" markdown>
+
+- [Using With Pull Request ID](pullrequest-id.md)
+- [Using With Repository Remote URL And Source Branch Name](repository-information.md)
+- [Using With Azure Pipelines](azure-pipelines.md)
+
+</div>
+
 !!! info
     There's a [demo repository](https://dev.azure.com/pberger/Cake.Issues-Demo){target="_blank"}
     available which you can fork and to which you can create pull requests to test the integration functionality.
diff --git a/docs/docs/documentation/pull-request-systems/azure-devops/features.md b/docs/docs/documentation/pull-request-systems/azure-devops/features.md
@@ -1,6 +1,7 @@
 ---
 title: Features
 description: Features of the Cake.Issues.PullRequests.AzureDevOps addin.
+icon: material/creation-outline
 ---
 
 The [Cake.Issues.PullRequests.AzureDevOps addin](https://cakebuild.net/extensions/cake-issues-pullrequests-azuredevops/){target="_blank"}
@@ -11,22 +12,20 @@ provides the following features.
 
 ## Basic features
 
-* Writes issues as comments to [Azure DevOps](https://azure.microsoft.com/en-us/services/devops/){target="_blank"} pull requests.
-* Identification of pull requests through source branch or pull request ID.
-* Comments written by the addin will be rendered with a specific icon corresponding to the state of the issue.
-* Adds rule number and, if provided by the issue provider, link to the rule description to the comment.
-* Support for issues messages formatted in Markdown format.
+- [x] Writes issues as comments to [Azure DevOps](https://azure.microsoft.com/en-us/services/devops/){target="_blank"} pull requests.
+- [x] Identification of pull requests through source branch or pull request ID.
+- [x] Comments written by the addin will be rendered with a specific icon corresponding to the state of the issue.
+- [x] Adds rule number and, if provided by the issue provider, link to the rule description to the comment.
+- [x] Support for issues messages formatted in Markdown format.
 
 ## Supported capabilities
 
 The [Cake.Issues.PullRequests.AzureDevOps addin](https://cakebuild.net/extensions/cake-issues-pullrequests-azuredevops/){target="_blank"}
 supports the following capabilities.
 
-|                  | Capability                     | Remarks                        |
-|------------------|--------------------------------|--------------------------------|
-| :material-check: | Checking commit ID             |                                |
-| :material-check: | Discussion threads             |                                |
-| :material-check: | Filtering by modified files    |                                |
+- [x] Checking commit ID
+- [x] Discussion threads
+- [x] Filtering by modified files
 
 ## Supported authentication methods
 

diff --git a/docs/docs/documentation/pull-request-systems/azure-devops/index.md b/docs/docs/documentation/pull-request-systems/azure-devops/index.md
@@ -4,4 +4,12 @@ description: Support for Azure DevOps.
 ---
 
 Support for Azure DevOps is implemented in the
-[Cake.Issues.PullRequests.AzureDevOps addin](https://www.nuget.org/packages/Cake.Issues.PullRequests.AzureDevOps).
+[Cake.Issues.PullRequests.AzureDevOps addin](https://cakebuild.net/extensions/cake-issues-pullrequests-azuredevops/){target="_blank"}.
+
+<div class="grid cards" markdown>
+
+- :material-creation-outline: [Features](features.md)
+- :material-cogs: [Setup](setup.md)
+- :material-test-tube: [Examples](examples/index.md)
+
+</div>
diff --git a/docs/docs/documentation/pull-request-systems/azure-devops/setup.md b/docs/docs/documentation/pull-request-systems/azure-devops/setup.md
@@ -1,6 +1,7 @@
 ---
 title: Setup
 description: Instructions how to setup the Cake.Issues.PullRequests.AzureDevOps addin.
+icon: material/cogs
 ---
 
 This page describes the different ways how the [Cake.Issues.PullRequests.AzureDevOps addin] can be setup.

diff --git a/docs/docs/documentation/pull-request-systems/github-actions/examples/index.md b/docs/docs/documentation/pull-request-systems/github-actions/examples/index.md
@@ -0,0 +1,11 @@
+---
+title: Examples
+description: Examples for using the Cake.Issues.PullRequests.GitHubActions addin.
+icon: material/test-tube
+---
+
+<div class="grid cards" markdown>
+
+- [Create Annotations In GitHub Actions](write-annotations.md)
+
+</div>
diff --git a/docs/docs/documentation/pull-request-systems/github-actions/features.md b/docs/docs/documentation/pull-request-systems/github-actions/features.md
@@ -1,25 +1,24 @@
 ---
 title: Features
 description: Features of the Cake.Issues.PullRequests.GitHubActions addin.
+icon: material/creation-outline
 ---
 
-The [Cake.Issues.PullRequests.GitHubActions addin] creates annotations from issues when running on GitHub actions.
+The [Cake.Issues.PullRequests.GitHubActions addin]{target="_blank"} creates annotations from issues when running on GitHub actions.
 
 ![Pull request integration](githubactions-pullrequest-integration.png "Pull request integration")
 
 ## Basic features
 
-* Reports issues as annotations to GitHub Actions builds.
-* Group issues in log output by provider and run information.
+- [x] Reports issues as annotations to GitHub Actions builds.
+- [x] Group issues in log output by provider and run information.
 
 ## Supported capabilities
 
-The [Cake.Issues.PullRequests.GitHubActions addin] doesn't support any additional capabilities.
+The [Cake.Issues.PullRequests.GitHubActions addin]{target="_blank"} doesn't support any additional capabilities.
 
-|                  | Capability                     | Remarks                        |
-|------------------|--------------------------------|--------------------------------|
-|                  | Checking commit ID             |                                |
-|                  | Discussion threads             |                                |
-|                  | Filtering by modified files    |                                |
+- [ ] Checking commit ID
+- [ ] Discussion threads
+- [ ] Filtering by modified files
 
-[Cake.Issues.PullRequests.GitHubActions addin]: https://www.nuget.org/packages/Cake.Issues.PullRequests.GitHubActions
+[Cake.Issues.PullRequests.GitHubActions addin]: https://cakebuild.net/extensions/cake-issues-pullrequests-githubactions/
diff --git a/docs/docs/documentation/pull-request-systems/github-actions/index.md b/docs/docs/documentation/pull-request-systems/github-actions/index.md
@@ -4,4 +4,11 @@ description: Support for GitHub Actions.
 ---
 
 Support for GitHub Actions is implemented in the
-[Cake.Issues.PullRequests.GitHubActions addin](https://www.nuget.org/packages/Cake.Issues.PullRequests.GitHubActions).
+[Cake.Issues.PullRequests.GitHubActions addin](https://cakebuild.net/extensions/cake-issues-pullrequests-githubactions/){target="_blank"}.
+
+<div class="grid cards" markdown>
+
+- :material-creation-outline: [Features](features.md)
+- :material-test-tube: [Examples](examples/index.md)
+
+</div>
diff --git a/docs/docs/documentation/report-formats/console/examples.md b/docs/docs/documentation/report-formats/console/examples.md
@@ -1,6 +1,7 @@
 ---
 title: Examples
 description: Examples for using the Cake.Issues.Reporting.Console addin.
+icon: material/test-tube
 ---
 
 The following example will print issues logged as warnings by MsBuild to the console.

diff --git a/docs/docs/documentation/report-formats/console/features.md b/docs/docs/documentation/report-formats/console/features.md
@@ -1,16 +1,17 @@
 ---
 title: Features
 description: Features of the Cake.Issues.Reporting.Console addin.
+icon: material/creation-outline
 ---
 
-The [Cake.Issues.Reporting.Console addin] provides the following features:
+The [Cake.Issues.Reporting.Console addin]{target="_blank"} provides the following features:
 
-* Prints issues containing line and column information.
-* Group issues by rule
+- [x] Prints issues containing line and column information.
+- [x] Group issues by rule
 
 Reports:
 
-* Number of issues by provider
-* Number of issues by priority for every provider and run
+- [x] Number of issues by provider
+- [x] Number of issues by priority for every provider and run
 
-[Cake.Issues.Reporting.Console addin]: https://www.nuget.org/packages/Cake.Issues.Reporting.Console
+[Cake.Issues.Reporting.Console addin]: https://cakebuild.net/extensions/cake-issues-reporting-console/
diff --git a/docs/docs/documentation/report-formats/console/index.md b/docs/docs/documentation/report-formats/console/index.md
@@ -4,4 +4,11 @@ description: Report format to print issues to the console.
 ---
 
 Support for printing issues to the console is implemented in the
-a [Cake.Issues.Reporting.Console addin](https://www.nuget.org/packages/Cake.Issues.Reporting.Console).
+a [Cake.Issues.Reporting.Console addin](https://cakebuild.net/extensions/cake-issues-reporting-console/){target="_blank"}.
+
+<div class="grid cards" markdown>
+
+- :material-creation-outline: [Features](features.md)
+- :material-test-tube: [Examples](examples.md)
+
+</div>
diff --git a/docs/docs/documentation/report-formats/generic/examples/index.cshtml b/docs/docs/documentation/report-formats/generic/examples/index.cshtml
diff --git a/docs/docs/documentation/report-formats/generic/examples/index.md b/docs/docs/documentation/report-formats/generic/examples/index.md
@@ -0,0 +1,12 @@
+---
+title: Examples
+description: Examples for using the Cake.Issues.Reporting.Generic addin.
+icon: material/test-tube
+---
+
+<div class="grid cards" markdown>
+
+- [Embedded Default Template](default-template.md)
+- [Custom Template](custom-template.md)
+
+</div>
diff --git a/docs/docs/documentation/report-formats/generic/features.md b/docs/docs/documentation/report-formats/generic/features.md
@@ -1,14 +1,15 @@
 ---
 title: Features
 description: Features of the Cake.Issues.Reporting.Generic addin.
+icon: material/creation-outline
 ---
 
 The [Cake.Issues.Reporting.Generic addin](https://cakebuild.net/extensions/cake-issues-reporting-generic/){target="_blank"}
 provides the following features:
 
-* Creates reports in any text based format like HTML or Markdown.
-* Provides out of the box templates
-* Possibility to use custom templates using Razor
+- [x] Creates reports in any text based format like HTML or Markdown.
+- [x] Provides out of the box templates
+- [x] Possibility to use custom templates using Razor
 
 !!! info
     See [Template Gallery] for a list of available out of the box and 3rd party templates.

diff --git a/docs/docs/documentation/report-formats/generic/index.md b/docs/docs/documentation/report-formats/generic/index.md
@@ -4,4 +4,12 @@ description: Report format to create reports in any text based format (HTML, Mar
 ---
 
 Support for creating reports in any text based format like HTML or Markdown is implemented in the
-[Cake.Issues.Reporting.Generic addin](https://www.nuget.org/packages/Cake.Issues.Reporting.Generic).
+[Cake.Issues.Reporting.Generic addin](https://cakebuild.net/extensions/cake-issues-reporting-generic/){target="_blank"}.
+
+<div class="grid cards" markdown>
+
+- :material-creation-outline: [Features](features.md)
+- :material-test-tube: [Examples](examples/index.md)
+- :material-image: [Template Gallery](templates/index.md)
+
+</div>
diff --git a/docs/docs/documentation/report-formats/generic/templates/index.md b/docs/docs/documentation/report-formats/generic/templates/index.md
@@ -1,4 +1,13 @@
 ---
 title: Template Gallery
 description: Gallery of available out of the box and 3rd party templates.
+icon: material/image
 ---
+
+<div class="grid cards" markdown>
+
+- [HTML DevExtreme Data Grid](htmldxdatagrid.md)
+- [HTML Data Table](htmldatatable.md)
+- [HTML Diagnostic](htmldiagnostic.md)
+
+</div>
diff --git a/docs/docs/documentation/report-formats/sarif/examples.md b/docs/docs/documentation/report-formats/sarif/examples.md
@@ -1,6 +1,7 @@
 ---
 title: Examples
 description: Examples for using the Cake.Issues.Reporting.Sarif addin.
+icon: material/test-tube
 ---
 
 The following example will create a SARIF report for issues logged as warnings by MsBuild.

diff --git a/docs/docs/documentation/report-formats/sarif/features.md b/docs/docs/documentation/report-formats/sarif/features.md
@@ -1,19 +1,20 @@
 ---
 title: Features
 description: Features of the Cake.Issues.Reporting.Sarif addin.
+icon: material/creation-outline
 ---
 
-The [Cake.Issues.Reporting.Sarif addin] provides the following features:
+The [Cake.Issues.Reporting.Sarif addin]{target="_blank"} provides the following features:
 
-* Creates SARIF compatible files.
+- [x] Creates SARIF compatible files.
 
 Supports the following properties in the SARIF report:
 
-* RuleId
-* Message
-* Kind
-* Level
-* Location
-* RuleUrl
+- [x] RuleId
+- [x] Message
+- [x] Kind
+- [x] Level
+- [x] Location
+- [x] RuleUrl
 
-[Cake.Issues.Reporting.Sarif addin]: https://www.nuget.org/packages/Cake.Issues.Reporting.Sarif
+[Cake.Issues.Reporting.Sarif addin]: https://cakebuild.net/extensions/cake-issues-reporting-sarif/
diff --git a/docs/docs/documentation/report-formats/sarif/index.md b/docs/docs/documentation/report-formats/sarif/index.md
@@ -4,4 +4,11 @@ description: Report format to create SARIF compatible reports.
 ---
 
 Support for creating SARIF compatible reports is implemented in the
-[Cake.Issues.Reporting.Sarif addin](https://www.nuget.org/packages/Cake.Issues.Reporting.Sarif).
+[Cake.Issues.Reporting.Sarif addin](https://cakebuild.net/extensions/cake-issues-reporting-sarif/){target="_blank"}.
+
+<div class="grid cards" markdown>
+
+- :material-creation-outline: [Features](features.md)
+- :material-test-tube: [Examples](examples.md)
+
+</div>
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -186,6 +186,7 @@ nav:
           - documentation/report-formats/generic/index.md
           - Features: documentation/report-formats/generic/features.md
           - Examples:
+            - documentation/report-formats/generic/examples/index.md
             - Embedded Default Template: documentation/report-formats/generic/examples/default-template.md
             - Custom Template: documentation/report-formats/generic/examples/custom-template.md
           - Template Gallery:
@@ -219,6 +220,7 @@ nav:
           - documentation/pull-request-systems/github-actions/index.md
           - Features: documentation/pull-request-systems/github-actions/features.md
           - Examples:
+            - documentation/pull-request-systems/github-actions/examples/index.md
             - Create annotations in GitHub Actions: documentation/pull-request-systems/github-actions/examples/write-annotations.md
     - How To Develop:
       - Extending: