docs(policy-reference): add more examples for existing built-in functions

[srenatus]

The policy reference contains a list of all the built-in functions; and examples for very few. It would be helpful for getting off the ground if some basic examples showed to to use a built-in.

This issue is broad and not meant to be fixed in a single sweep. Any added examples will be valuable.

[stale]

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

[Joffref]

At this time on-boarding some built-in functions is quite hard such as graph related functions.

I think this a good pick, I would enjoy to participate, is it possible to create a draft PR ?

I there a list (with prioritization) of function that need documentation ?

[srenatus]

I've got ideas about how to deal with this, centered around well-annotated example rego files.

So if you'd like to pick a builtin to document, please create a rego file like docs/examples/io.jwt.decode_verify.rego,

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 {
  # ...
}

with a few of these in place, we can then worry about hooking them into the website docs automatically, which is a bit of a different story.

[VaishnavSreekumar]

Hi @srenatus, thanks for the guidance on this issue.

I’m a first-time contributor and would like to help by adding examples for one built-in using the
docs/examples/<builtin>.rego format you suggested.

I’m thinking of starting with a commonly used builtin (for example: string, time, or net related).
Before I begin, is there any builtin you’d currently prefer to see documented first?

If not, I’ll pick one and open a draft PR following the example structure you described.

[srenatus]

Thanks for reaching out! We've had some improvements to the docs, and I'm a little out of the loop as to what's planned, let's include @charlieegan3 here! @charlieegan3: Do you think this issue is still accurate? How would it look in the current state of builtins docs on the website?

[charlieegan3]

hey @vaish123-fullstck, thanks for your interest here.

Examples can be created in the following way:

• create the various files and metadata files, see here for the example for jwks: https://github.com/open-policy-agent/opa/tree/main/docs/docs/policy-reference/_examples/io.jwt/decode_verify/jwks
• then reference the example in the relevant page, e.g. https://github.com/open-policy-agent/opa/blob/main/docs/docs/policy-reference/builtins/tokens.mdx?plain=1#L114

Please choose some built-ins that you use in your own Rego and have used yourself that you think would be helpful to document for others.

If you are looking for a starting point, please consider adding one for units.parse here: https://www.openpolicyagent.org/docs/policy-reference/builtins/units