website: auto-generate builtin documentation from source (incl. examples)

[srenatus]

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.

[stale]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[stale]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.