opa
opa copied to clipboard
website: auto-generate builtin documentation from source (incl. examples)
With #4080 giving us named arguments, we can use that information to autogenerate docs for the function arguments, incl descriptions, on the website.
This could look like the folllowing:
a. named args and descriptions are added to ast.Builtin (or so) via #4080 b. it becomes part of the capabilities.json c. the website build is modified to read the capabilities.json (copied into website/data) and uses that to render built-in function headers
In a similar way, examples could be added to the website docs.
One approach here would be to use rego files with metadata, like
package examples.builtins["io.jwt.decode_verify"]
# METADATA
# description: |
# When used in a simple case, io.jwt.decode_verify does this and that.
test_simple {
jwt := "..."
criteria := { }
io.jwt.decode_verify(jwt, criteria) == { ... }
}
# METADATA
# description: To check issuer, the `iss` criterium needs to be provided
test_issuer {
# ...
}
A helper golang script would read those, and generate some markdown stubs from them, to be included (manually, per-builtin, via shortcodes, maybe?) in the policy-reference.
This way, we should be able to gradually shift the content from the current unstructured markdown format to the in-code Builtin structures, and the example rego files.
Additionally, a CI job would run opa test
on those examples.
Related: #2650.
This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.
This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.