feature: Documentation command #1009

xNok · 2024-09-30T09:10:13Z

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.

document/template.go

document/metadata.go

document/metadata_test.go

internal/commands/document.go

document/metadata.go

document/metadata_test.go

document/template.go

jalseth

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

document/template.go

document/template_test.go

document/metadata_test.go

xNok · 2024-10-24T18:05:48Z

@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 · 2024-11-12T17:51:25Z

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

Signed-off-by: Alexandre Couedelo <[email protected]> refactor: change the way we access annotations I am testing different way to generate the doc. Having the compiler object is much easier than the annotation set only Signed-off-by: Alexandre Couedelo <[email protected]>

Signed-off-by: Alexandre Couedelo <[email protected]>

Signed-off-by: Alexandre Couedelo <[email protected]> fix: make title coherent in submodules documentation Signed-off-by: Alexandre Couedelo <[email protected]>

Signed-off-by: Alexandre Couedelo <[email protected]> chore: ignore golden files in git Signed-off-by: Alexandre Couedelo <[email protected]> chore: document and test the custom template feature Signed-off-by: Alexandre Couedelo <[email protected]> chore: linting Signed-off-by: Alexandre Couedelo <[email protected]>

…9.0 (open-policy-agent#1010) Bumps [github.com/open-policy-agent/opa](https://github.com/open-policy-agent/opa) from 0.68.0 to 0.69.0. - [Release notes](https://github.com/open-policy-agent/opa/releases) - [Changelog](https://github.com/open-policy-agent/opa/blob/main/CHANGELOG.md) - [Commits](open-policy-agent/opa@v0.68.0...v0.69.0) --- updated-dependencies: - dependency-name: github.com/open-policy-agent/opa dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Signed-off-by: Alexandre Couedelo <[email protected]>

build(deps): bump github.com/open-policy-agent/opa from 0.68.0 to 0.69.0 (open-policy-agent#1010) Bumps [github.com/open-policy-agent/opa](https://github.com/open-policy-agent/opa) from 0.68.0 to 0.69.0. - [Release notes](https://github.com/open-policy-agent/opa/releases) - [Changelog](https://github.com/open-policy-agent/opa/blob/main/CHANGELOG.md) - [Commits](open-policy-agent/opa@v0.68.0...v0.69.0) --- updated-dependencies: - dependency-name: github.com/open-policy-agent/opa dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Signed-off-by: Alexandre Couedelo <[email protected]> chore: go mod tidy

Signed-off-by: Alexandre Couedelo <[email protected]>

jalseth Signed-off-by: Alexandre Couedelo <[email protected]>

Signed-off-by: Alexandre Couedelo <[email protected]>

the name of the variable has changed to be more meaningful Signed-off-by: Alexandre Couedelo <[email protected]>

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

xNok force-pushed the documentation-command branch from 92993db to f9f3d0e Compare September 30, 2024 09:11

xNok force-pushed the documentation-command branch from 3d36716 to 73114d4 Compare October 7, 2024 14:39

boranx reviewed Oct 7, 2024

View reviewed changes

document/template.go Outdated Show resolved Hide resolved

document/metadata.go Show resolved Hide resolved

document/metadata.go Show resolved Hide resolved

document/metadata_test.go Outdated Show resolved Hide resolved

internal/commands/document.go Outdated Show resolved Hide resolved

xNok force-pushed the documentation-command branch 4 times, most recently from 191ca6e to 5b32548 Compare October 9, 2024 12:38