Skip to content

Commit

Permalink
Move documentation for issue providers (#803)
Browse files Browse the repository at this point in the history
  • Loading branch information
@pascalberger
pascalberger authored Dec 10, 2024
2 parents 6cb17bf + 2eaa8ba commit a40fa3d
Show file tree
Hide file tree
Showing 19 changed files with 611 additions and 0 deletions.
67 changes: 67 additions & 0 deletions docs/input/docs/issue-providers/docfx/examples.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
---
Order: 30
Title: Examples
Description: Examples for using the Cake.Issues.DocFx addin.
---
The following example will call [DocFx] to generate the documentation and outputs the number of warnings.

To call [DocFx] from a Cake script you can use the [Cake.DocFx] addin.

```csharp
#addin "Cake.DocFx"
```

To read issues from DocFx log files you need to import the core addin and the DocFx support:

```csharp
#addin "Cake.Issues"
#addin "Cake.Issues.DocFx"
```

:::{.alert .alert-warning}
Please note that you always should pin addins to a specific version to make sure your builds are deterministic and
won't break due to updates to one of the addins.

See [pinning addin versions](https://cakebuild.net/docs/tutorials/pinning-cake-version#pinning-addin-version) for details.
:::

We need some global variables:

```csharp
var logPath = @"c:\build\docfx.log";
var repoRootPath = @"c:\repo";
var docRootPath = @"docs";
```

The following task will build the [DocFx] project and write a log file:

```csharp
Task("Build-Documentation").Does(() =>
{
// Run DocFx.
DocFxBuild(new DocFxBuildSettings()
{
LogPath = logPath
});
});
```

Finally you can define a task where you call the core addin with the desired issue provider.

```csharp
Task("Read-Issues")
.IsDependentOn("Build-Documentation")
.Does(() =>
{
// Read Issues.
var issues =
ReadIssues(
DocFxIssuesFromFilePath(logPath, docRootPath),
repoRootPath);

Information("{0} issues are found.", issues.Count());
});
```

[DocFx]: https://dotnet.github.io/docfx/
[Cake.DocFx]: https://www.nuget.org/packages/Cake.DocFx/
43 changes: 43 additions & 0 deletions docs/input/docs/issue-providers/docfx/features.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
Order: 20
Title: Features
Description: Features of the Cake.Issues.DocFx addin.
---
The [Cake.Issues.DocFx addin] provides the following features.

# Basic features

* Reads warnings from [DocFx] log files.

:::{.alert .alert-info}
[DocFx] can be run with [Cake.DocFx] addin.
:::

# Supported IIssue properties

| | Property | Remarks |
|--------------------------------------------------------------------|-----------------------------------|---------------------------------|
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.ProviderType` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.ProviderName` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.Run` | Can be set while reading issues |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Identifier` | Set to `IIssue.MessageText` |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.ProjectName` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.ProjectFileRelativePath` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.AffectedFileRelativePath` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Line` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.EndLine` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.Column` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.EndColumn` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.FileLink` | Can be set while reading issues |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.MessageText` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.MessageHtml` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.MessageMarkdown` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Priority` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.PriorityName` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Rule` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.RuleUrl` | |

[Cake.Issues.DocFx addin]: https://www.nuget.org/packages/Cake.Issues.DocFx
[DocFx]: https://dotnet.github.io/docfx/
[Cake.DocFx]: https://www.nuget.org/packages/Cake.DocFx
[IssuePriority.Warning]: ../../../api/Cake.Issues/IssuePriority/7A0CE07F
12 changes: 12 additions & 0 deletions docs/input/docs/issue-providers/docfx/index.cshtml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
Title: DocFx
Description: Issue provider which allows you to read warnings logged by DocFx.
---
<p>@Html.Raw(Model.String(DocsKeys.Description))</p>

<p>
Support for reading warnings reported by <a href="https://dotnet.github.io/docfx/" target="_blank">DocFx</a>
is implemented in the <a href="https://www.nuget.org/packages/Cake.Issues.DocFx" target="_blank">Cake.Issues.DocFx addin</a>.
</p>

@Html.Partial("_ChildPages")
9 changes: 9 additions & 0 deletions docs/input/docs/issue-providers/docfx/requirements.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
Order: 10
Title: Requirements
Description: Requirements for the Cake.Issues.DocFx addin.
---
The requirements for using the [Cake.Issues.DocFx addin] are listed in the [release notes] for any specific version.

[Cake.Issues.DocFx addin]: https://www.nuget.org/packages/Cake.Issues.DocFx
[release notes]: release-notes
44 changes: 44 additions & 0 deletions docs/input/docs/issue-providers/eslint/features.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
Order: 20
Title: Features
Description: Features of the Cake.Issues.EsLint addin.
---
The [Cake.Issues.EsLint addin] provides the following features.

# Basic features

* Reads issues reported by ESLint.
* Provides URLs for all issues.
* Support for custom URL resolving using the [EsLintAddRuleUrlResolver] alias.

# Supported log file formats

* [EsLintJsonFormat] alias for reading issues from log files created by [ESLint json formatter].

# Supported IIssue properties

| | Property | Remarks |
|--------------------------------------------------------------------|-----------------------------------|---------------------------------|
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.ProviderType` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.ProviderName` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.Run` | Can be set while reading issues |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Identifier` | Set to `IIssue.MessageText` |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.ProjectName` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.ProjectFileRelativePath` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.AffectedFileRelativePath` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Line` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.EndLine` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Column` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.EndColumn` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.MessageText` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.MessageHtml` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.MessageMarkdown` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Priority` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.PriorityName` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Rule` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.RuleUrl` | Support for custom rules can be added through a custom [EsLintAddRuleUrlResolver] |

[Cake.Issues.EsLint addin]: https://www.nuget.org/packages/Cake.Issues.EsLint
[ESLint json formatter]: https://eslint.org/docs/user-guide/formatters/#json
[EsLintAddRuleUrlResolver]: ../../../api/Cake.Issues.EsLint/EsLintIssuesAliases/D64301E6
[EsLintJsonFormat]: ../../../api/Cake.Issues.EsLint/EsLintIssuesAliases/230C6E27
12 changes: 12 additions & 0 deletions docs/input/docs/issue-providers/eslint/index.cshtml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
Title: ESLint
Description: Issue provider which allows you to read issues logged by ESLint.
---
<p>@Html.Raw(Model.String(DocsKeys.Description))</p>

<p>
Support for reading issues reported by <a href="https://eslint.org/" target="_blank">ESLint</a>
is implemented in the <a href="https://www.nuget.org/packages/Cake.Issues.EsLint" target="_blank">Cake.Issues.EsLint addin</a>.
</p>

@Html.Partial("_ChildPages")
9 changes: 9 additions & 0 deletions docs/input/docs/issue-providers/eslint/requirements.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
Order: 10
Title: Requirements
Description: Requirements for the Cake.Issues.EsLint addin.
---
The requirements for using the [Cake.Issues.EsLint addin] are listed in the [release notes] for any specific version.

[Cake.Issues.EsLint addin]: https://www.nuget.org/packages/Cake.Issues.EsLint
[release notes]: release-notes
66 changes: 66 additions & 0 deletions docs/input/docs/issue-providers/inspectcode/examples.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
Order: 30
Title: Examples
Description: Examples for using the Cake.Issues.InspectCode addin.
---
The following example will call [JetBrains InspectCode] and output the number of warnings.

To call [JetBrains InspectCode] from a Cake script you need to add the `JetBrains.ReSharper.CommandLineTools`:

```csharp
#tool "nuget:?package=JetBrains.ReSharper.CommandLineTools"
```

To read issues from InspectCode log files you need to import the core addin and the InspectCode support:

```csharp
#addin "Cake.Issues"
#addin "Cake.Issues.InspectCode"
```

:::{.alert .alert-warning}
Please note that you always should pin addins and tools to a specific version to make sure your builds are deterministic and
won't break due to updates to one of the packages.

See [pinning addin versions](https://cakebuild.net/docs/tutorials/pinning-cake-version#pinning-addin-version) for details.
:::

We need some global variables:

```csharp
var logPath = @"c:\build\inspectcode.xml";
var repoRootPath = @"c:\repo";
```

The following task will run [JetBrains InspectCode] and write a log file:

```csharp
Task("Analyze-Project").Does(() =>
{
// Run InspectCode.
var settings = new InspectCodeSettings() {
OutputFile = logPath
};

InspectCode(repoRootPath.CombineWithFilePath("MySolution.sln"), settings);
});
```

Finally you can define a task where you call the core addin with the desired issue provider.

```csharp
Task("Read-Issues")
.IsDependentOn("Analyze-Project")
.Does(() =>
{
// Read Issues.
var issues =
ReadIssues(
InspectCodeIssuesFromFilePath(logPath),
repoRootPath);

Information("{0} issues are found.", issues.Count());
});
```

[JetBrains InspectCode]: https://www.jetbrains.com/help/resharper/InspectCode.html
38 changes: 38 additions & 0 deletions docs/input/docs/issue-providers/inspectcode/features.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
Order: 20
Title: Features
Description: Features of the Cake.Issues.InspectCode addin.
---
The [Cake.Issues.InspectCode addin] provides the following features:

# Basic features

* Reads warnings from [JetBrains InsepectCode] log files.
* Provides URLs for issues containing a Wiki URL.

# Supported IIssue properties

| | Property | Remarks |
|--------------------------------------------------------------------|-----------------------------------|----------------------------------|
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.ProviderType` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.ProviderName` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.Run` | Can be set while reading issues |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Identifier` | Set to `IIssue.MessageText` |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.ProjectName` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.ProjectFileRelativePath` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.AffectedFileRelativePath` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Line` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.EndLine` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.Column` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.EndColumn` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.FileLink` | Can be set while reading issues |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.MessageText` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.MessageHtml` | |
| <span class="glyphicon glyphicon-remove" style="color:red"></span> | `IIssue.MessageMarkdown` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Priority` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.PriorityName` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.Rule` | |
| <span class="glyphicon glyphicon-ok" style="color:green"></span> | `IIssue.RuleUrl` | For issues containing a Wiki Url |

[JetBrains InsepectCode]: https://www.jetbrains.com/help/resharper/2017.1/InspectCode.html
[Cake.Issues.InspectCode addin]: https://www.nuget.org/packages/Cake.Issues.InspectCode
12 changes: 12 additions & 0 deletions docs/input/docs/issue-providers/inspectcode/index.cshtml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
Title: InspectCode
Description: Issue provider which allows you to read issues logged by JetBrains Inspect Code.
---
<p>@Html.Raw(Model.String(DocsKeys.Description))</p>

<p>
Support for reading issues reported by <a href="https://www.jetbrains.com/help/resharper/2017.1/InspectCode.html" target="_blank">JetBrains Inspect Code</a>
is implemented in the <a href="https://www.nuget.org/packages/Cake.Issues.InspectCode" target="_blank">Cake.Issues.InspectCode addin</a>.
</p>

@Html.Partial("_ChildPages")
9 changes: 9 additions & 0 deletions docs/input/docs/issue-providers/inspectcode/requirements.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
Order: 10
Title: Requirements
Description: Requirements for the Cake.Issues.Inspectcode addin.
---
The requirements for using the [Cake.Issues.InspectCode addin] are listed in the [release notes] for any specific version.

[Cake.Issues.InspectCode addin]: https://www.nuget.org/packages/Cake.Issues.InspectCode
[release notes]: release-notes
Loading

0 comments on commit a40fa3d

Please sign in to comment.