docs: Add docs for location metadata and outputters (#1205)

* docs: Add docs for location metadata and outputters

Also, move pre-commit docs to their own page to keep the introductory
usage docs as brief as possible.

Signed-off-by: James Alseth <james@jalseth.me>

* docs: Format docs with mdformat

This ensures consistency and makes the docs easier to read when
viewing the markdown files directly rather than the rendered HTML.

Signed-off-by: James Alseth <james@jalseth.me>

---------

Signed-off-by: James Alseth <james@jalseth.me>

Author: jalseth

.gitignore

@@ -8,6 +8,9 @@ site
 .DS*
 .idea
 
+# Running docs site locally
+Pipfile*
+
 # NodeJS files/dirs created when installing bats
 node_modules/
 package.json

Makefile

@@ -60,12 +60,12 @@ lint: ## Lints Conftest.
 ratchet-update:
 	@ratchet update .github/workflows/*.yaml
 
+.PHONY: format-docs
+format-docs:
+	@mdformat --wrap 80 docs
+
 .PHONY: all
 all: lint build test test-examples test-acceptance ## Runs all linting and tests.
 
 help:
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m\033[0m\n"} /^[$$()% a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
-
-#
-##@ Releases
-#

docs/README.md

@@ -1,17 +1,20 @@
 # Conftest documentation
 
-The documentation for Conftest is stored as markdown files in this directory, and a documentation site generated using [Mkdocs](https://www.mkdocs.org/).
+The documentation for Conftest is stored as markdown files in this directory,
+and a documentation site generated using [Mkdocs](https://www.mkdocs.org/).
 
-Conftest provides a `Pipfile` for managing the required dependencies. At the top level of this repository (ie. _not_ in the `docs` directory) run:  
+Conftest provides a `Pipfile` for managing the required dependencies. At the top
+level of this repository (ie. _not_ in the `docs` directory) run:
 
 ```console
 pipenv install
 ```
 
-With the dependencies installed you can run the site locally. Any modifications to the files in `docs` will be automatically rebuilt.
+With the dependencies installed you can run the site locally. Any modifications
+to the files in `docs` will be automatically rebuilt.
 
 ```console
-pipenv run mkdir serve
+pipenv run mkdocs serve
 INFO    -  Building documentation...
 INFO    -  Cleaning site directory
 INFO    -  Documentation built in 0.45 seconds

docs/debug.md

@@ -1,6 +1,8 @@
 # Debugging policies
 
-When working on more complex queries (or when learning Rego), it's useful to see exactly how the policy is applied. For this purpose you can use the `--trace` flag. This will output a large trace from Open Policy Agent like the following:
+When working on more complex queries (or when learning Rego), it's useful to see
+exactly how the policy is applied. For this purpose you can use the `--trace`
+flag. This will output a large trace from Open Policy Agent like the following:
 
 ```console
 $ conftest test --trace deployment.yaml
@@ -111,7 +113,11 @@ TRAC | Redo data.main.deny = _
 
 ## Using trace with other output formats
 
-You can use the `--trace` flag together with any output format. When using `--trace` with formats like `--output=table` or `--output=json`, the trace information will be written to stderr while the formatted output will be written to stdout. This allows you to capture trace information for debugging while still using your preferred output format.
+You can use the `--trace` flag together with any output format. When using
+`--trace` with formats like `--output=table` or `--output=json`, the trace
+information will be written to stderr while the formatted output will be written
+to stdout. This allows you to capture trace information for debugging while
+still using your preferred output format.
 
 For example:
 

docs/documentation.md

@@ -2,7 +2,8 @@
 
 ## Document your policies
 
-OPA has introduced a standard way to document policies called [Metadata](https://www.openpolicyagent.org/docs/latest/policy-language/#metadata). 
+OPA has introduced a standard way to document policies called
+[Metadata](https://www.openpolicyagent.org/docs/latest/policy-language/#metadata).
 This format allows for structured in code documentation of policies.
 
 ```opa
@@ -17,29 +18,34 @@ allow if {
 }
 ```
 
-For the generated documentation to make sense your `packages` should be documented with at least the `title` field 
-and `rules` should have both `title` and `description`. This will ensure that no section is empty in your 
+For the generated documentation to make sense your `packages` should be
+documented with at least the `title` field and `rules` should have both `title`
+and `description`. This will ensure that no section is empty in your
 documentations.
 
 ## Generate the documentation
 
-In code documentation is great but what we often want it to later generated an actual static reference documentation.
-The `doc` command will retrieve all annotation of a targeted module and generate a markdown documentation for it.
+In code documentation is great but what we often want it to later generated an
+actual static reference documentation. The `doc` command will retrieve all
+annotation of a targeted module and generate a markdown documentation for it.
 
 ```bash
 conftest doc path/to/policy
 ```
 
 ## Use your own template
 
-You can override the [default template](https://raw.githubusercontent.com/open-policy-agent/conftest/refs/heads/master/document/resources/document.md) with your own template
+You can override the
+[default template](https://raw.githubusercontent.com/open-policy-agent/conftest/refs/heads/master/document/resources/document.md)
+with your own template
 
 ```aiignore
 conftest -t template.md path/tp/policies
 ```
 
-All annotation are returned as a sorted list of all annotations, grouped by the path and location of their targeted 
-package or rule. For instance using this template
+All annotation are returned as a sorted list of all annotations, grouped by the
+path and location of their targeted package or rule. For instance using this
+template
 
 ```bash
 {{ range . -}}

docs/examples.md

@@ -1,35 +1,36 @@
 # Examples
 
-You can find examples using various other tools in the `examples` directory, including:
+You can find examples using various other tools in the `examples` directory,
+including:
 
-* [AWS SAM Framework](https://github.com/open-policy-agent/conftest/tree/master/examples/awssam)
-* [Builtin-Errors](https://github.com/open-policy-agent/conftest/tree/master/examples/builtin-errors)
-* [Capabilities](https://github.com/open-policy-agent/conftest/tree/master/examples/capabilities)
-* [Combine](https://github.com/open-policy-agent/conftest/tree/master/examples/combine)
-* [Configfile](https://github.com/open-policy-agent/conftest/tree/master/examples/configfile)
-* [CUE](https://github.com/open-policy-agent/conftest/tree/master/examples/cue)
-* [Cyclonedx](https://github.com/open-policy-agent/conftest/tree/master/examples/cyclonedx)
-* [Data](https://github.com/open-policy-agent/conftest/tree/master/examples/data)
-* [Docker compose](https://github.com/open-policy-agent/conftest/tree/master/examples/compose)
-* [Dockerfile](https://github.com/open-policy-agent/conftest/tree/master/examples/docker)
-* [Dotenv](https://github.com/open-policy-agent/conftest/tree/master/examples/dotenv)
-* [EDN](https://github.com/open-policy-agent/conftest/tree/master/examples/edn)
-* [Exceptions](https://github.com/open-policy-agent/conftest/tree/master/examples/exceptions)
-* [HCL](https://github.com/open-policy-agent/conftest/tree/master/examples/hcl1)
-* [HCL 2](https://github.com/open-policy-agent/conftest/tree/master/examples/hcl2)
-* [HOCON](https://github.com/open-policy-agent/conftest/tree/master/examples/hocon)
-* [Ignore](https://github.com/open-policy-agent/conftest/tree/master/examples/ignore)
-* [INI](https://github.com/open-policy-agent/conftest/tree/master/examples/ini)
-* [Jsonnet](https://github.com/open-policy-agent/conftest/tree/master/examples/jsonnet)
-* [Kubernetes](https://github.com/open-policy-agent/conftest/tree/master/examples/kubernetes)
-* [Kustomize](https://github.com/open-policy-agent/conftest/tree/master/examples/kustomize)
-* [Properties](https://github.com/open-policy-agent/conftest/tree/master/examples/properties)
-* [Report](https://github.com/open-policy-agent/conftest/tree/master/examples/report)
-* [Serverless Framework](https://github.com/open-policy-agent/conftest/tree/master/examples/serverless)
-* [Spdx](https://github.com/open-policy-agent/conftest/tree/master/examples/spdx)
-* [Strict-rules](https://github.com/open-policy-agent/conftest/tree/master/examples/strict-rules/policy)
-* [Textproto](https://github.com/open-policy-agent/conftest/tree/master/examples/textproto)
-* [Traefik](https://github.com/open-policy-agent/conftest/tree/master/examples/traefik)
-* [Typescript](https://github.com/open-policy-agent/conftest/tree/master/examples/ts)
-* [VCL](https://github.com/open-policy-agent/conftest/tree/master/examples/vcl)
-* [XML](https://github.com/open-policy-agent/conftest/tree/master/examples/xml)
+- [AWS SAM Framework](https://github.com/open-policy-agent/conftest/tree/master/examples/awssam)
+- [Builtin-Errors](https://github.com/open-policy-agent/conftest/tree/master/examples/builtin-errors)
+- [Capabilities](https://github.com/open-policy-agent/conftest/tree/master/examples/capabilities)
+- [Combine](https://github.com/open-policy-agent/conftest/tree/master/examples/combine)
+- [Configfile](https://github.com/open-policy-agent/conftest/tree/master/examples/configfile)
+- [CUE](https://github.com/open-policy-agent/conftest/tree/master/examples/cue)
+- [Cyclonedx](https://github.com/open-policy-agent/conftest/tree/master/examples/cyclonedx)
+- [Data](https://github.com/open-policy-agent/conftest/tree/master/examples/data)
+- [Docker compose](https://github.com/open-policy-agent/conftest/tree/master/examples/compose)
+- [Dockerfile](https://github.com/open-policy-agent/conftest/tree/master/examples/docker)
+- [Dotenv](https://github.com/open-policy-agent/conftest/tree/master/examples/dotenv)
+- [EDN](https://github.com/open-policy-agent/conftest/tree/master/examples/edn)
+- [Exceptions](https://github.com/open-policy-agent/conftest/tree/master/examples/exceptions)
+- [HCL](https://github.com/open-policy-agent/conftest/tree/master/examples/hcl1)
+- [HCL 2](https://github.com/open-policy-agent/conftest/tree/master/examples/hcl2)
+- [HOCON](https://github.com/open-policy-agent/conftest/tree/master/examples/hocon)
+- [Ignore](https://github.com/open-policy-agent/conftest/tree/master/examples/ignore)
+- [INI](https://github.com/open-policy-agent/conftest/tree/master/examples/ini)
+- [Jsonnet](https://github.com/open-policy-agent/conftest/tree/master/examples/jsonnet)
+- [Kubernetes](https://github.com/open-policy-agent/conftest/tree/master/examples/kubernetes)
+- [Kustomize](https://github.com/open-policy-agent/conftest/tree/master/examples/kustomize)
+- [Properties](https://github.com/open-policy-agent/conftest/tree/master/examples/properties)
+- [Report](https://github.com/open-policy-agent/conftest/tree/master/examples/report)
+- [Serverless Framework](https://github.com/open-policy-agent/conftest/tree/master/examples/serverless)
+- [Spdx](https://github.com/open-policy-agent/conftest/tree/master/examples/spdx)
+- [Strict-rules](https://github.com/open-policy-agent/conftest/tree/master/examples/strict-rules/policy)
+- [Textproto](https://github.com/open-policy-agent/conftest/tree/master/examples/textproto)
+- [Traefik](https://github.com/open-policy-agent/conftest/tree/master/examples/traefik)
+- [Typescript](https://github.com/open-policy-agent/conftest/tree/master/examples/ts)
+- [VCL](https://github.com/open-policy-agent/conftest/tree/master/examples/vcl)
+- [XML](https://github.com/open-policy-agent/conftest/tree/master/examples/xml)

docs/exceptions.md

@@ -1,8 +1,12 @@
 # Exceptions
 
-There might be cases where rules might not apply under certain circumstances. For those occasions, you can use `exceptions`. Exceptions are also written in rego, and allow you to specify policies for when a given `deny` or `violation` rule does not apply. 
+There might be cases where rules might not apply under certain circumstances.
+For those occasions, you can use `exceptions`. Exceptions are also written in
+rego, and allow you to specify policies for when a given `deny` or `violation`
+rule does not apply.
 
-Inputs matched by the `exception` will be exempted from the rules specified in `rules`, prefixed by `deny_` or `violation_`:
+Inputs matched by the `exception` will be exempted from the rules specified in
+`rules`, prefixed by `deny_` or `violation_`:
 
 ```rego
 exception contains rules if {
@@ -12,19 +16,24 @@ exception contains rules if {
 }
 ```
 
-The above would provide an exception from `deny_foo` and `violation_foo` as well as `deny_bar` and `violation_bar`.
+The above would provide an exception from `deny_foo` and `violation_foo` as well
+as `deny_bar` and `violation_bar`.
 
-Note that if you specify the empty string, the exception will match *all* rules named `deny` or `violation`. It is recommended to use identifiers in your rule names to allow for targeted exceptions.
+Note that if you specify the empty string, the exception will match *all* rules
+named `deny` or `violation`. It is recommended to use identifiers in your rule
+names to allow for targeted exceptions.
 
 ## Reporting
 
-Exceptions are reported as a separate tally in Conftest's output, so you can detect when exceptions are being made. For example, you might see this summary: 
+Exceptions are reported as a separate tally in Conftest's output, so you can
+detect when exceptions are being made. For example, you might see this summary:
 
 `2 tests, 1 passed, 0 warnings, 0 failures, 1 exception`.
 
 ## Examples
 
-In the below example, a Kubernetes deployment named `can-run-as-root` will be allowed to run as root, while others will not:
+In the below example, a Kubernetes deployment named `can-run-as-root` will be
+allowed to run as root, while others will not:
 
 ```rego
 package main