docs: Update config cli docs (#1584)

* docs: Update cli and config documentation

Place them in own sections not in readme.

#1558 (comment)

Signed-off-by: Charlie Egan <charlie@styra.com>

* docs: Add community footers

Signed-off-by: Charlie Egan <charlie@styra.com>

* docs: add more to the next steps

Signed-off-by: Charlie Egan <charlie@styra.com>

* docs: Correct yaml format

And update readme

Signed-off-by: Charlie Egan <charlie@styra.com>

* docs: Add community footers to new pages

Signed-off-by: Charlie Egan <charlie@styra.com>

---------

Signed-off-by: Charlie Egan <charlie@styra.com>

Author: Charlie Egan

README.md

@@ -22,7 +22,8 @@ while IFS= read -r file; do
     cat "$section_path" >> "$tmpfile"
     echo -e "\n" >> "$tmpfile"
   else
-    echo "Warning: Section file not found: $section_path" >&2
+    echo "Section file not found: $section_path" >&2
+    exit 1
   fi
 done < "$MANIFEST"
 

build/update-readme.sh

@@ -2,7 +2,8 @@
 
 Its possible to use Regal to lint your Rego policies in your CI/CD pipeline(s)!
 
-This document will guide you on how to do so.
+This document will guide you on how to do so. Please also review the
+[CLI](./cli) documentation for more information on the available options.
 
 ## GitHub Actions
 
@@ -52,3 +53,8 @@ regal_lint_policies:
 
 The above will run Regal on the `policy` directory when a merge request is created or updated and will show linting
 violations as part of the merge request.
+
+## Community
+
+For questions, discussions and announcements related to Styra products, services and open source projects, please join
+the Styra community on [Slack](https://inviter.co/styra)!

docs/cicd.md

@@ -0,0 +1,54 @@
+# CLI
+
+Regal's CLI is the main way to interact with Regal. In order to support
+different use cases (Local, CI, etc.) Regal's CLI is designed with a number of
+different formats and exit behaviors.
+
+## Output Formats
+
+The `regal lint` command allows specifying the output format by using the `--format` flag. The available output formats
+are:
+
+- `pretty` (default) - Human-readable table-like output where each violation is printed with a detailed explanation
+- `compact` - Human-readable output where each violation is printed on a single line
+- `json` - JSON output, suitable for programmatic consumption
+- `github` - GitHub [workflow command](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions)
+  output, ideal for use in GitHub Actions. Annotates PRs and creates a
+  [job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary)
+  from the linter report
+- `sarif` - [SARIF](https://sarifweb.azurewebsites.net/) JSON output, for consumption by tools processing code analysis
+  reports
+- `junit` - JUnit XML output, e.g. for CI servers like GitLab that show these results in a merge request.
+
+## Exit Codes
+
+Exit codes are used to indicate the result of the `lint` command. The `--fail-level` provided for `regal lint` may be
+used to change the exit code behavior, and allows a value of either `warning` or `error` (default).
+
+If `--fail-level error` is supplied, exit code will be zero even if warnings are present:
+
+- `0`: no errors were found
+- `0`: one or more warnings were found
+- `3`: one or more errors were found
+
+This is the default behavior.
+
+If `--fail-level warning` is supplied, warnings will result in a non-zero exit code:
+
+- `0`: no errors or warnings were found
+- `2`: one or more warnings were found
+- `3`: one or more errors were found
+
+## OPA Check and Strict Mode
+
+OPA itself provides a "linter" of sorts, via the `opa check` command and its `--strict` flag. This checks the provided
+Rego files not only for syntax errors, but also for OPA
+[strict mode](https://www.openpolicyagent.org/docs/policy-language/#strict-mode) violations. Most of the strict
+mode checks from before OPA 1.0 have now been made default checks in OPA, and only two additional checks are currently
+provided by the `--strict` flag. Those are both important checks not covered by Regal though, so our recommendation is
+to run `opa check --strict` against your policies before linting with Regal.
+
+## Community
+
+For questions, discussions and announcements related to Styra products, services and open source projects, please join
+the Styra community on [Slack](https://inviter.co/styra)!

docs/cli.md

@@ -0,0 +1,2 @@
+sidebar_position: 4
+sidebar_label: CLI

docs/cli.md.yaml

@@ -0,0 +1 @@
+{ "collapsed": true, "label": "Configuration" }

docs/configuration/_category_.json

@@ -1,6 +1,4 @@
-<!-- markdownlint-disable MD041 -->
-
-## Capabilities
+# Capabilities
 
 By default, Regal will lint your policies using the
 [capabilities](https://www.openpolicyagent.org/docs/deployments/#capabilities) of the latest version of OPA
@@ -57,7 +55,7 @@ capabilities:
         type: object
 ```
 
-### Loading Capabilities from URLs
+## Loading Capabilities from URLs
 
 Starting with Regal version v0.26.0, Regal can load capabilities from URLs with the `http`, or `https` schemes using
 the `capabilities.from.url` config key. For example, to load capabilities from `https://example.org/capabilities.json`,
@@ -69,11 +67,16 @@ capabilities:
     url: https://example.org/capabilities.json
 ```
 
-### Supported Engines
+## Supported Engines
 
 Regal includes capabilities files for the following engines:
 
 | Engine | Website                                                         | Description          |
 | ------ | --------------------------------------------------------------- | -------------------- |
 | `opa`  | [OPA website](https://www.openpolicyagent.org/)                 | Open Policy Agent    |
 | `eopa` | [Enterprise OPA website](https://www.styra.com/enterprise-opa/) | Styra Enterprise OPA |
+
+## Community
+
+For questions, discussions and announcements related to Styra products, services and open source projects, please join
+the Styra community on [Slack](https://inviter.co/styra)!

docs/readme-sections/capabilities.md docs/configuration/capabilities.mddocs/readme-sections/capabilities.md renamed to docs/configuration/capabilities.md

@@ -0,0 +1 @@
+sidebar_position: 5

docs/configuration/capabilities.md.yaml

@@ -1,6 +1,4 @@
-<!-- markdownlint-disable MD041 -->
-
-## Ignoring Rules
+# Ignoring Rules
 
 If one of Regal's rules doesn't align with your team's preferences, don't worry! Regal is not meant to be the law,
 and some rules may not make sense for your project, or parts of it.
@@ -29,7 +27,7 @@ It's also possible to ignore messages on a per-file basis. The available methods
 - [Ignoring Files Globally](#ignoring-files-globally) or
   [Ignoring a Rule in Some Files](#ignoring-a-rule-in-some-files).
 
-### Ignoring a Rule in Config
+## Ignoring a Rule in Config
 
 If you want to ignore a rule, set its level to `ignore` in the configuration file:
 
@@ -41,7 +39,7 @@ rules:
       level: ignore
 ```
 
-### Ignoring a Category in Config
+## Ignoring a Category in Config
 
 If you want to ignore a category of rules, set its default level to `ignore` in the configuration file:
 
@@ -52,7 +50,7 @@ rules:
       level: ignore
 ```
 
-### Ignoring All Rules in Config
+## Ignoring All Rules in Config
 
 If you want to ignore all rules, set the default level to `ignore` in the configuration file:
 
@@ -71,7 +69,7 @@ rules:
 
 **Tip**: providing a comment on ignored rules is a good way to communicate why the decision was made.
 
-### Ignoring a Rule in Some Files
+## Ignoring a Rule in Some Files
 
 You can use the `ignore` attribute inside any rule configuration to provide a list of files, or patterns, that should
 be ignored for that rule:
@@ -89,7 +87,7 @@ rules:
         - "scratch.rego"
 ```
 
-### Ignoring Files Globally
+## Ignoring Files Globally
 
 **Note**: Ignoring files will disable most language server features
 for those files. Only formatting will remain available.
@@ -105,7 +103,7 @@ ignore:
   - "*_tmp.rego"
 ```
 
-### Inline Ignore Directives
+## Inline Ignore Directives
 
 If you'd like to ignore a specific violation in a file, you can add an ignore directive above the line in question, or
 alternatively on the same line to the right of the expression:
@@ -129,7 +127,7 @@ Note that at this point in time, Regal only considers the same line or the line
 does not apply to entire blocks of code (like rules, functions or even packages). See [configuration](#configuration)
 if you want to ignore certain rules altogether.
 
-### Ignoring Rules via CLI Flags
+## Ignoring Rules via CLI Flags
 
 For development and testing, rules or classes of rules may quickly be enabled or disabled using the relevant CLI flags
 for the `regal lint` command:
@@ -143,3 +141,8 @@ for the `regal lint` command:
 - `--ignore-files` ignores files using glob patterns, overriding `ignore` in the config file (may be repeated)
 
 **Note:** all CLI flags override configuration provided in file.
+
+## Community
+
+For questions, discussions and announcements related to Styra products, services and open source projects, please join
+the Styra community on [Slack](https://inviter.co/styra)!

docs/readme-sections/ignore-rules.md docs/configuration/ignore-rules.mddocs/readme-sections/ignore-rules.md renamed to docs/configuration/ignore-rules.md

@@ -0,0 +1 @@
+sidebar_position: 6