Improve recipe documentation (#868)

cake-contrib · Dec 29, 2024 · 702bf08 · 702bf08
1 parent e994828
commit 702bf08
Show file tree

Hide file tree

Showing 10 changed files with 288 additions and 105 deletions.
diff --git a/docs/docs/blog/posts/2020-08-22-cake-issues-v0.9.0-released.md b/docs/docs/blog/posts/2020-08-22-cake-issues-v0.9.0-released.md
@@ -140,7 +140,7 @@ across all runs.
 [Cake.Issues.Recipe], the Cake Recipe script which you can integrate into your build script for easy integration of
 full feature issue management, has been updated to version 0.4.0, bringing all the new features of Cake.Issues 0.9.0.
 
-[Cake.Issues.Recipe]: ../../documentation/recipe/overview.md
+[Cake.Issues.Recipe]: ../../documentation/recipe/index.md
 
 ## Updating from previous versions
 

diff --git a/docs/docs/blog/posts/2021-08-31-cake-issues-markdownlint-v1.1.0.md b/docs/docs/blog/posts/2021-08-31-cake-issues-markdownlint-v1.1.0.md
@@ -41,4 +41,4 @@ To update to the new version bump the version of the addin.
 
 [MarkdownlintCliJsonLogFileFormat]: https://cakebuild.net/api/Cake.Issues.Markdownlint/MarkdownlintIssuesAliases/36DE6F5F
 [MarkdownlintCliLogFileFormat]: https://cakebuild.net/api/Cake.Issues.Markdownlint/MarkdownlintIssuesAliases/B518F49E
-[Cake Issues recipes]: ../../documentation/recipe/overview.md
+[Cake Issues recipes]: ../../documentation/recipe/index.md
diff --git a/docs/docs/documentation/features.md b/docs/docs/documentation/features.md
@@ -17,7 +17,7 @@ description: Overview about core features.
     It handles all the parsing, integration with build and pull request systems for you,
     using the individual Cake Issues addins.
 
-    [:octicons-arrow-right-24: Recipes](recipe/overview.md)
+    [:octicons-arrow-right-24: Recipes](recipe/index.md)
 
 </div>
 

diff --git a/docs/docs/documentation/recipe/configuration.md b/docs/docs/documentation/recipe/configuration.md
diff --git a/docs/docs/documentation/recipe/overview.md → docs/docs/documentation/recipe/index.md b/docs/docs/documentation/recipe/overview.md → docs/docs/documentation/recipe/index.md
@@ -11,8 +11,21 @@ They support different linters based on the linting log files you pass it and in
 
 There are two flavors available:
 
-* [Cake.Issues.Recipe]: For [Cake .NET Tool], [Cake runner for .NET Framework] or [Cake runner for .NET Core]
-* [Cake.Frosting.Issues.Recipe]: For [Cake Frosting]
+<div class="grid cards" markdown>
+
+-   :material-receipt-text: [Cake.Issues.Recipe]
+
+    ---
+
+    For [Cake .NET Tool]{target="_blank"}
+
+-   :material-receipt-text: [Cake.Frosting.Issues.Recipe]
+
+    ---
+
+    For [Cake Frosting]{target="_blank"}
+
+</div>
 
 ## Supported tools
 
@@ -22,29 +35,49 @@ See [supported tools] for a list of supported linters, build servers and pull re
 
 Cake.Issues recipes will add the following addins to your build:
 
-| Addin Cake.Issues.Recipe                                | Addin.Frosting.Issues.Recipe                                     | Remarks |
-|---------------------------------------------------------|------------------------------------------------------------------|-|
-| [Cake.Git] 5.0.1                                        | [Cake.Frosting.Git] 5.0.1                                        | Only used if `RepositoryInfoProvider` type is set to `RepositoryInfoProviderType.CakeGit`. See [Git repository information configuration] for details. |
-| [Cake.Issues] 5.0.1                                     | [Cake.Issues] 5.0.1                                              | |
-| [Cake.Issues.MsBuild] 5.0.1                             | [Cake.Frosting.Issues.MsBuild] 5.0.1                             | |
-| [Cake.Issues.InspectCode] 5.0.1                         | [Cake.Frosting.Issues.InspectCode] 5.0.1                         | |
-| [Cake.Issues.Markdownlint] 5.0.1                        | [Cake.Frosting.Issues.Markdownlint] 5.0.1                        | |
-| [Cake.Issues.EsLint] 5.0.1                              | [Cake.Frosting.Issues.EsLint] 5.0.1                              | |
-| [Cake.Issues.Sarif] 5.0.1                               | [Cake.Frosting.Issues.Sarif] 5.0.1                               | |
-| [Cake.Issues.Reporting] 5.0.1                           | [Cake.Frosting.Issues.Reporting] 5.0.1                           | |
-| [Cake.Issues.Reporting.Generic] 5.0.1                   | [Cake.Frosting.Issues.Reporting.Generic] 5.0.1                   | |
-| [Cake.Issues.Reporting.Sarif] 5.0.1                     | [Cake.Frosting.Issues.Reporting.Sarif] 5.0.1                     | |
-| [Cake.Issues.PullRequests] 5.0.1                        | [Cake.Frosting.Issues.PullRequests] 5.0.1                        | |
-| [Cake.Issues.PullRequests.AppVeyor] 5.0.1               | [Cake.Frosting.Issues.PullRequests.AppVeyor] 5.0.1               | |
-| [Cake.Issues.PullRequests.AzureDevOps] 5.0.1            | [Cake.Frosting.Issues.PullRequests.AzureDevOps] 5.0.1            | |
-| [Cake.Issues.PullRequests.GitHubActions] 5.0.1          | [Cake.Frosting.Issues.PullRequests.GitHubActions] 5.0.1          | |
-| [Cake.AzureDevOps] 5.0.0                                | [Cake.AzureDevOps] 5.0.0                                         | |
+=== "Cake.Issues.Recipe"
+
+    | Addin                                                     | Version |  Remarks |
+    |-----------------------------------------------------------|---------|-|
+    | [Cake.Git]{target="_blank"}                               | 5.0.1   | Only used if `RepositoryInfoProvider` type is set to `RepositoryInfoProviderType.CakeGit`. See [Git repository information configuration] for details. |
+    | [Cake.Issues]{target="_blank"}                            | 5.0.1   | |
+    | [Cake.Issues.MsBuild]{target="_blank"}                    | 5.0.1   | |
+    | [Cake.Issues.InspectCode]{target="_blank"}                | 5.0.1   | |
+    | [Cake.Issues.Markdownlint]{target="_blank"}               | 5.0.1   | |
+    | [Cake.Issues.EsLint]{target="_blank"}                     | 5.0.1   | |
+    | [Cake.Issues.Sarif]{target="_blank"}                      | 5.0.1   | |
+    | [Cake.Issues.Reporting]{target="_blank"}                  | 5.0.1   | |
+    | [Cake.Issues.Reporting.Generic]{target="_blank"}          | 5.0.1   | |
+    | [Cake.Issues.Reporting.Sarif]{target="_blank"}            | 5.0.1   | |
+    | [Cake.Issues.PullRequests]{target="_blank"}               | 5.0.1   | |
+    | [Cake.Issues.PullRequests.AppVeyor]{target="_blank"}      | 5.0.1   | |
+    | [Cake.Issues.PullRequests.AzureDevOps]{target="_blank"}   | 5.0.1   | |
+    | [Cake.Issues.PullRequests.GitHubActions]{target="_blank"} | 5.0.1   | |
+    | [Cake.AzureDevOps]{target="_blank"}                       | 5.0.0   | |
+
+=== "Cake.Frosting.Issues.Recipe"
+
+    | Addin                                                                    | Version | Remarks |
+    |--------------------------------------------------------------------------|---------|-|
+    | [Cake.Frosting.Git]{target="_blank"}                               | 5.0.1   | Only used if `RepositoryInfoProvider` type is set to `RepositoryInfoProviderType.CakeGit`. See [Git repository information configuration] for details. |
+    | [Cake.Issues]{target="_blank"}                                     | 5.0.1   | |
+    | [Cake.Frosting.Issues.MsBuild]{target="_blank"}                    | 5.0.1   | |
+    | [Cake.Frosting.Issues.InspectCode]{target="_blank"}                | 5.0.1   | |
+    | [Cake.Frosting.Issues.Markdownlint]{target="_blank"}               | 5.0.1   | |
+    | [Cake.Frosting.Issues.EsLint]{target="_blank"}                     | 5.0.1   | |
+    | [Cake.Frosting.Issues.Sarif]{target="_blank"}                      | 5.0.1   | |
+    | [Cake.Frosting.Issues.Reporting]{target="_blank"}                  | 5.0.1   | |
+    | [Cake.Frosting.Issues.Reporting.Generic]{target="_blank"}          | 5.0.1   | |
+    | [Cake.Frosting.Issues.Reporting.Sarif]{target="_blank"}            | 5.0.1   | |
+    | [Cake.Frosting.Issues.PullRequests]{target="_blank"}               | 5.0.1   | |
+    | [Cake.Frosting.Issues.PullRequests.AppVeyor]{target="_blank"}      | 5.0.1   | |
+    | [Cake.Frosting.Issues.PullRequests.AzureDevOps]{target="_blank"}   | 5.0.1   | |
+    | [Cake.Frosting.Issues.PullRequests.GitHubActions]{target="_blank"} | 5.0.1   | |
+    | [Cake.AzureDevOps]{target="_blank"}                                | 5.0.0   | |
 
 [Cake.Issues.Recipe]: https://www.nuget.org/packages/Cake.Issues.Recipe
 [Cake.Frosting.Issues.Recipe]: https://www.nuget.org/packages/Cake.Frosting.Issues.Recipe
 [Cake .NET Tool]: https://cakebuild.net/docs/running-builds/runners/dotnet-tool
-[Cake runner for .NET Framework]: https://cakebuild.net/docs/running-builds/runners/cake-runner-for-dotnet-framework
-[Cake runner for .NET Core]: https://cakebuild.net/docs/running-builds/runners/cake-runner-for-dotnet-core
 [Cake Frosting]: https://cakebuild.net/docs/running-builds/runners/cake-frosting
 [supported tools]: supported-tools.md
 [Git repository information configuration]: configuration.md#git-repository-information

diff --git a/docs/docs/documentation/recipe/supported-tools.md b/docs/docs/documentation/recipe/supported-tools.md
@@ -9,18 +9,38 @@ Cake.Issues recipes support reading issues from different tools and integrates w
 
 Cake.Issues recipes support reading issues from output of the following tools:
 
-| Tool                              | Format                                 | Cake.Issues.Recipe Methods                                                                     | Cake.Frosting.Issues.Recipe Method                                                                     |
-|-----------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
-| MsBuild                           | [MSBuild Extension Pack XmlFileLogger] | `IssuesParameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMsBuildXmlFileLoggerLogFile*()` | `IssuesContext.Parameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMsBuildXmlFileLoggerLogFile*()` |
-| MsBuild                           | Binary Log File                        | `IssuesParameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMsBuildBinaryLogFile*()`        | `IssuesContext.Parameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMsBuildBinaryLogFile*()`        |
-| JetBrains InspectCode (ReSharper) |                                        | `IssuesParameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddInspectCodeLogFile*()`          | `IssuesContext.Parameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddInspectCodeLogFile*()`          |
-| markdownlint                      | [markdownlint-cli]                     | `IssuesParameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMarkdownlintCliLogFile*()`      | `IssuesContext.Parameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMarkdownlintCliLogFile*()`      |
-| markdownlint                      | [markdownlint-cli] with `--json`       | `IssuesParameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMarkdownlintCliJsonLogFile*()`  | `IssuesContext.Parameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMarkdownlintCliJsonLogFile*()`  |
-| markdownlint                      | [markdownlint] version 1               | `IssuesParameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMarkdownlintV1LogFile*()`       | `IssuesContext.Parameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddMarkdownlintV1LogFile*()`       |
-| [ESLint]                          | [json formatter]                       | `IssuesParameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddEsLintJsonLogFile*()`           | `IssuesContext.Parameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddEsLintJsonLogFile*()`           |
-| Any SARIF compatible tool         | [SARIF]                                | `IssuesParameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddSarifLogFile*()`                | `IssuesContext.Parameters.InputFiles.`<br/>&nbsp;&nbsp;&nbsp;&nbsp;`AddSarifLogFile*()`                |
-
-[MSBuild Extension Pack XmlFileLogger]: http://www.msbuildextensionpack.com/help/4.0.5.0/html/242ab4fd-c2e2-f6aa-325b-7588725aed24.htm
+=== "Cake.Issues.Recipe"
+
+    | Tool                              | Format                                                  | IssuesParameters.InputFiles Method  |
+    |-----------------------------------|---------------------------------------------------------|-------------------------------------|
+    | MsBuild                           | [MSBuild Extension Pack XmlFileLogger]{target="_blank"} | `AddMsBuildXmlFileLoggerLogFile*()` |
+    | MsBuild                           | Binary Log File                                         | `AddMsBuildBinaryLogFile*()`        |
+    | JetBrains InspectCode (ReSharper) | [xml]{target="_blank"}                                  | `AddInspectCodeLogFile*()`          |
+    | markdownlint                      | [markdownlint-cli]{target="_blank"} default format      | `AddMarkdownlintCliLogFile*()`      |
+    | markdownlint                      | [markdownlint-cli]{target="_blank"} with `--json`       | `AddMarkdownlintCliJsonLogFile*()`  |
+    | markdownlint                      | [markdownlint]{target="_blank"} version 1               | `AddMarkdownlintV1LogFile*()`       |
+    | [ESLint]                          | [json formatter]{target="_blank"}                       | `AddEsLintJsonLogFile*()`           |
+    | Any SARIF compatible tool         | [SARIF]{target="_blank"}                                | `AddSarifLogFile*()`                |
+
+=== "Cake.Frosting.Issues.Recipe"
+
+    | Tool                              | Format                                                  | IssuesContext.Parameters.InputFiles Method |
+    |-----------------------------------|---------------------------------------------------------|--------------------------------------------|
+    | MsBuild                           | [MSBuild Extension Pack XmlFileLogger]{target="_blank"} | `AddMsBuildXmlFileLoggerLogFile*()`        |
+    | MsBuild                           | Binary Log File                                         | `AddMsBuildBinaryLogFile*()`               |
+    | JetBrains InspectCode (ReSharper) | [xml]{target="_blank"}                                  | `AddInspectCodeLogFile*()`                 |
+    | markdownlint                      | [markdownlint-cli]{target="_blank"} default format      | `AddMarkdownlintCliLogFile*()`             |
+    | markdownlint                      | [markdownlint-cli]{target="_blank"} with `--json`       | `AddMarkdownlintCliJsonLogFile*()`         |
+    | markdownlint                      | [markdownlint]{target="_blank"} version 1               | `AddMarkdownlintV1LogFile*()`              |
+    | [ESLint]                          | [json formatter]{target="_blank"}                       | `AddEsLintJsonLogFile*()`                  |
+    | Any SARIF compatible tool         | [SARIF]{target="_blank"}                                | `AddSarifLogFile*()`                       |
+
+!!! tip
+
+    See [Supported tools](../supported-tools.md) for a list of tools supporting the SARIF format.
+
+[MSBuild Extension Pack XmlFileLogger]: https://github.com/mikefourie-zz/MSBuildExtensionPack/blob/master/Solutions/Main/Loggers/Framework/XmlFileLogger.cs
+[xml]: https://www.jetbrains.com/help/resharper/InspectCode.html#alternative-output-formats
 [markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli
 [markdownlint]: https://github.com/DavidAnson/markdownlint
 [ESLint]: https://eslint.org/
@@ -31,17 +51,58 @@ Cake.Issues recipes support reading issues from output of the following tools:
 
 Cake.Issues recipes integrates with the following build systems:
 
-| Build System                   | Write issues to build server     | Issues summary     | Full issues report |
-|--------------------------------|----------------------------------|--------------------|--------------------|
-| AppVeyor                       | :material-check:                 |                    | :material-check:   |
-| Azure Pipelines (Azure DevOps) | :material-check: (Only first 10) | :material-check:   | :material-check:   |
-| GitHub Actions                 | :material-check:                 |                    |                    |
+=== "AppVeyor"
+
+    <div class="annotate" markdown>
+
+    - [x] Write issues to build server
+    - [ ] Issues summary
+    - [x] Full issues report
+
+    </div>
+
+=== "Azure Pipelines"
+
+    <div class="annotate" markdown>
+
+    - [x] Write issues to build server (1)
+    - [x] Issues summary
+    - [x] Full issues report
+
+    </div>
+
+    1.  Only first 10
+
+=== "GitHub Actions"
+
+    <div class="annotate" markdown>
+
+    - [x] Write issues to build server
+    - [ ] Issues summary
+    - [ ] Full issues report
+
+    </div>
 
 ## Pull request systems
 
 Cake.Issues recipes integrates with the following pull request systems:
 
-| Pull Request System        | Write issues to pull requests                     | Set pull request status |
-|----------------------------|---------------------------------------------------|-------------------------|
-| Azure Repos (Azure DevOps) | :material-check:                                  | :material-check:        |
-| GitHub                     | :material-check: (When build from GitHub Actions) |                         |
+=== "Azure Repos"
+
+    <div class="annotate" markdown>
+
+    - [x] Write issues to pull requests
+    - [x] Set pull request status
+
+    </div>
+
+=== "GitHub"
+
+    <div class="annotate" markdown>
+
+    - [x] Write issues to pull requests (1)
+    - [ ] Set pull request status
+
+    </div>
+
+    1.  When build from GitHub Actions