open-policy-agent / conftest

Write tests against structured configuration data using the Open Policy Agent Rego query language
https://conftest.dev
Other
2.88k stars 307 forks source link

feature: Documentation command #1009

Open xNok opened 1 month ago

xNok commented 1 month ago

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)

xNok commented 4 weeks ago

@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.

image

image

boranx commented 1 week ago

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