feature: Documentation command

[xNok]

I found myself wanting to generate reference documentation for my policies, and I figured it would be nice if this was a built-in feature of conftest.

While the way of structuring the documentation can be opinionated, I think using the FlatAnnotationsRefSet is a safe bet, as OPA's core does all the heavy lifting of organizing annotations and rules.

My initial attempt was to combine FlatAnnotationsRefSet and Go-template and offer the least opinionated approach to documentation format that can be easily overridden. However, I had some trouble properly formatting titles (H1, H2, H3, etc...) and had to introduce some custom logic to handle it. (As a side note this could potentially be handles by adding template function libraries such as sprig)

[boranx]

hey @xNok

Thanks for bringing this together, I actually very liked the idea of using go templates and embedding both so if the user has their own, overriding it to balance flexibility with functionality.
This can help us collectively gather feedback on how users actually use it and refactor to get it closer to the user needs.
+1 from me on implementation.
Just left some comments at first glance, will look at more.

[jalseth]

Thanks for the PR! It is very thorough and including documentation on how to use the feature is much appreciated.

[xNok]

@jalseth, I have addressed your comment. It seems there is a broken test, and it fails on master and my last heavy_check_mark: revision. I have no clue what could be causing it to fail.

[boranx]

@xNok Please rebase the branch, the CI should now be passing

[boranx]

LGTM, thanks for crafting this feature 🎉
We may further shape it based on user feedback as it's used more and more, but for now it's good to go.

kindly pinging @jalseth / @jpreese for sign-off

[mrueg]

fwiw, this feature looks similar to https://github.com/plexsystems/konstraint/blob/main/docs/cli/konstraint_doc.md maybe it makes sense to integrate the feature from konstraint?

[xNok]

fwiw, this feature looks similar to https://github.com/plexsystems/konstraint/blob/main/docs/cli/konstraint_doc.md maybe it makes sense to integrate the feature from konstraint?

Kubetmetes are not the only thing you can validate with conftest, we use it for terraform and Backstage manifest, in which cases it makes no sense to use Konstraint

[anderseknert]

This is neat! Thanks for working on this. Let's have it merged!

[boranx]

Finally getting this over the finish line—appreciate everyone's input!