Improve key concepts (#851)

docs/docs/documentation/features.md

@@ -0,0 +1,161 @@
+---
+title: Features
+description: Overview about core features.
+---
+
+## Ready To Use Distributions
+
+<div class="grid cards" markdown>
+
+-   :material-arrow-collapse-all:{ .lg .middle } __Cake Recipe Packages__
+
+    ---
+
+    Cake Issues recipes provide build scripts, delivered as a NuGet package,
+    which can be used inside your projects Cake build to add issue management.
+
+    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)
+
+</div>
+
+## Reading & Creating Issues
+
+<div class="grid cards" markdown>
+
+-   :material-import:{ .lg .middle } __Read issues provided by tools__
+
+    ---
+
+    The `ReadIssues` aliases can be used for reading issues reported by a linter to tool using an [issue provider].
+
+    There are overloads for reading using a single or multiple [issue provider].
+
+    [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#Reading-Issues){target="_blank"}
+
+-   :material-creation-outline:{ .lg .middle } __Create issues in your build__
+
+    ---
+
+    The `NewIssue` aliases can be used for creating issues in the build script.
+
+    [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#Creating-Issues){target="_blank"}
+
+-   :material-file-link:{ .lg .middle } __Support for file links__
+
+    ---
+
+    Support for creating links to file & location on source code hosting system (GitHub, Azure Repos, etc).
+
+    [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#File-Linking){target="_blank"}
+
+-   :material-swap-vertical-bold:{ .lg .middle } __Issue serialization__
+
+    ---
+
+    Support for serializing and deserializing created issues and issues read from tools.
+
+    [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#Issue-Serialization){target="_blank"}
+
+-   :material-format-title:{ .lg .middle } __Support for multiple message formats__
+
+    ---
+
+    Support for reading issues in multiple formats (Plain text, Markdown, HTML) if supported by [issue provider].
+
+-   :material-information:{ .lg .middle } __Support for run information__
+
+    ---
+
+    Support for passing additional run information to identify specific runs.
+
+</div>
+
+## Breaking builds
+
+<div class="grid cards" markdown>
+
+-   :material-exclamation:{ .lg .middle } __Fail builds on reported issues__
+
+    ---
+
+    The `BreakBuildOnIssues` aliases can be used for failing builds if specific issues were reported.
+
+    There are overloads for failing if issues of certain minimum priority or issue providers are found,
+    or by passing any custom function.
+
+    [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues/#Build-Breaking){target="_blank"}
+
+</div>
+
+## Reporting
+
+<div class="grid cards" markdown>
+
+-   :material-monitor-dashboard:{ .lg .middle } __Create reports__
+
+    ---
+
+    The `CreateIssueReport` aliases can be used for creating reports in a supported [reporting format].
+
+    There are overloads for reading issues from a single or multiple [issue provider] or for passing an existing list of issues.
+
+    [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues-reporting/#Creating-Issue-Reports){target="_blank"}
+
+</div>
+
+## Build & Pull Request System Integration
+
+<div class="grid cards" markdown>
+
+-   :material-comment-text:{ .lg .middle } __Add comments to pull requests__
+
+    ---
+
+    The `ReportIssuesToPullRequest` aliases can be used for writing issues as comments to [pull requests].
+
+    There are overloads for reading issues from a single or multiple [issue provider] or for passing an existing list of issues.
+
+    [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues-pullrequests/#Reporting-Issues-To-Pull-Requests){target="_blank"}
+
+-   :material-message-plus:{ .lg .middle } __Report issues to build runs__
+
+    ---
+
+    The `ReportIssuesToPullRequest` aliases can be used for reporting issues to [build runs].
+
+    There are overloads for reading issues from a single or multiple [issue provider] or for passing an existing list of issues.
+
+    [:octicons-arrow-right-24: Aliases](https://cakebuild.net/extensions/cake-issues-pullrequests/#Reporting-Issues-To-Pull-Requests){target="_blank"}
+
+-   :material-filter:{ .lg .middle } __Issue filters__
+
+    ---
+
+    Support for passing custom issue filter routines.
+
+    [:octicons-arrow-right-24: Setting](https://cakebuild.net/api/Cake.Issues.PullRequests/IReportIssuesToPullRequestSettings/48CB35E4){target="_blank"}
+
+-   :material-car-speed-limiter:{ .lg .middle } __Limit reported issues__
+
+    ---
+
+    Advanced support to limit number of maximum issues per run, across multiple runs or per issue provider through settings.
+
+    [:octicons-arrow-right-24: Settings](https://cakebuild.net/api/Cake.Issues.PullRequests/IReportIssuesToPullRequestSettings/){target="_blank"}
+
+-   :material-comment-check:{ .lg .middle } __Automatic comment resolving__
+
+    ---
+
+    If supported by the [pull request system], comments for issues are automatic resolved if fixed in subsequent commits.
+
+</div>
+
+[issue provider]: issue-providers/index.md
+[reporting format]: report-formats/index.md
+[pull requests]: pull-request-systems/index.md
+[build runs]: pull-request-systems/index.md
+[pull request system]: pull-request-systems/index.md

docs/docs/documentation/how-cake-issues-works.md

@@ -0,0 +1,45 @@
+---
+title: How Cake Issues Works
+description: Overview about the architecture of Cake Issues.
+---
+
+The Cake Issues addins are built in a modular architecture, allowing to easily
+enhance it for supporting additional analyzers, linters, report formats and pull request systems.
+
+![Architecture Overview](assets/images/overview.png "Architecture Overview")
+
+## Cake.Issues addin
+
+The `Cake.Issues` addin provides aliases for creating issues or reading issues using one or more issue providers.
+
+Support for different code analyzers and linters is provided through [issue provider] addins
+which cover a wide range of [linters and tools].
+
+The issues are read into [IIssue](https://cakebuild.net/api/Cake.Issues/IIssue/){target="_blank"} objects
+which then can be passed to [Cake.Issues.Reporting addin](#cakeissuesreporting-addin),
+[Cake.Issues.PullRequests addin](#cakeissuespullrequests-addin) or further processed in the build script.
+
+The use of [issue provider] addins, which contain the parsing logic for individual tool output formats,
+and the use of [IIssue](https://cakebuild.net/api/Cake.Issues/IIssue/){target="_blank"} as common data structure,
+allows to abstract the tooling output from other concerns like integration with
+build systems, pull request workflow or the creation of reports.
+
+## Cake.Issues.Reporting addin
+
+The `Cake.Issues.Reporting` addin provides aliases for creating reports for issues
+which are read or have been created using the [Cake.Issues addin](#cakeissues-addin).
+
+Support for different report formats is provided through [report format] addins.
+
+## Cake.Issues.PullRequests addin
+
+The `Cake.Issues.PullRequests` addin provides aliases for reporting issues
+which are read or have been created using the [Cake.Issues addin](#cakeissues-addin)
+as comments to pull requests or builds.
+
+Support for different pull request systems is provided through [pull request system] addins.
+
+[issue provider]: issue-providers/index.md
+[linters and tools]: supported-tools.md
+[report format]: report-formats/index.md
+[pull request system]: pull-request-systems/index.md

docs/docs/documentation/overview.md

@@ -0,0 +1,106 @@
+---
+title: Introduction
+description: Introduction
+---
+
+The Cake.Issues addins for the [Cake build automation system](https://cakebuild.net){target="_blank"}
+offer an extensive and flexible solution for reading linting issues.
+
+Cake.Issues redefines issue management within the Cake build system by offering a comprehensive, universal, and extensible solution.
+The unique capabilities of the addins empower development teams to enforce coding standards, generate insightful reports,
+seamlessly incorporate various linting tools, and streamlining the integration with pull requests.
+With its [modular architecture] and extensive [set of aliases](https://cakebuild.net/extensions/cake-issues/){target="_blank"},
+Cake.Issues provides a future-proof infrastructure for issue management in Cake builds,
+fostering a more efficient and adaptable development process.
+
+## Unique Problem Solving
+
+Some examples how Cake.Issues can help development teams to improve code quality.
+
+### Break build on linting issues
+
+Cake.Issues provides a seamless integration, allowing you to enforce coding standards by breaking builds when linting issues are detected.
+
+[:octicons-arrow-right-24: Aliases for build breaking](https://cakebuild.net/extensions/cake-issues/#Build-Breaking){target="_blank"}
+
+### Pull Requests integration
+
+Ensure linting issues are promptly addressed by having them reported as comments on pull requests.
+Cake.Issues bridges the gap between linting tools and version control systems, fostering efficient collaboration during code reviews.
+
+[:octicons-arrow-right-24: Integrate with pull request systems](pull-request-systems/index.md)
+
+### Reports
+
+Craft detailed and visually appealing reports for linting issues directly within your Cake build.
+The addins facilitates easy identification and resolution of linting concerns, enhancing the overall code quality.
+
+[:octicons-arrow-right-24: Creating Reports](report-formats/index.md)
+
+## Universal Compatibility
+
+### Diverse Linting Tool Support
+
+Regardless of the linting tools you use, Cake.Issues ensures that you're not left out.
+Cake.Issues supports a variety of analyzers and linters, allowing you to incorporate new tools effortlessly
+while maintaining integration with existing ones.
+
+[:octicons-arrow-right-24: Supported Tools](supported-tools.md)
+
+### Build System Agnosticism
+
+Embrace the freedom to choose the build system that best suit your needs.
+If your current build system lacks tasks for reporting issues in pull requests, Cake.Issues steps in to fill that void seamlessly.
+In the case of using multiple CI services, Cake.Issues guarantees a consistent feature set across all of them.
+
+[:octicons-arrow-right-24: Supported Build and pull request systems](pull-request-systems/index.md)
+
+## Unprecedented Extensibility
+
+### Modular Architecture
+
+The Cake.Issues addin breaks away from the norm by offering a modular architecture.
+Comprising over 15 distinct addins, it presents a cohesive solution through more than 75 aliases for Cake builds,
+providing unparalleled flexibility.
+
+[:octicons-arrow-right-24: Architecture](how-cake-issues-works.md)
+
+### Extensible Infrastructure
+
+Designed with extensibility in mind, Cake.Issues provides extension points for supporting additional
+analyzers, linters,report formats, and code review systems.
+This adaptability ensures that your build scripts can evolve with the ever-changing landscape of development tools.
+
+[:octicons-arrow-right-24: Documentation](extending/index.md)
+
+<!-- Do you want to break your build on JetBrains InspectCode issues?
+Do you want to create nice reports for StyleCop issues in your code?
+Do you want to have ESLint issues reported as comments to pull requests?
+The Cake.Issues addins allows you to do this and much more.
+Read issues from different analyzer or linters, create reports or add them as comments to pull requests.
+
+While some linting tools provide nice reporting capabilities, others don't.
+Some build systems provide tasks to report issues into pull requests.
+But if you're using another build system your out of luck.
+Maybe you found a new nice linting tool which does exactly what you need,
+but probably it won't integrate well with your existing other linting tools.
+
+The Cake.Issues addins tries to solve this, by providing a common and extensible infrastructure
+for issue management in Cake build scripts.
+
+Unlike other Cake addins, the Cake Issues addin consists of over 15 different addins,
+working together and providing over 75 aliases which can be used in Cake build scripts to work with issues.
+The addins are built in a [modular architecture] and are providing different [extension points] which allows to easily
+enhance them for supporting additional analyzers, linters, report formats and code review systems.
+
+!!! tip
+    To get started you can use one of the [Cake.Issues recipes], which bring support for different linters and
+    integration with build and pull request systems out-of-the box in a single and easy to use NuGet package.
+
+[:fontawesome-solid-video: Presentation](https://gitpitch.com/pascalberger/Cake.Issues-Presentation){ .md-button }
+
+[:fontawesome-solid-graduation-cap: Tutorials](../usage/index.md){ .md-button } -->
+
+[modular architecture]: how-cake-issues-works.md
+<!-- [extension points]: ../extending/index.md
+[Cake.Issues recipes]: ../recipe/overview.md -->