docs: Improve user experience of the built in function reference

[charlieegan3]

The current reference for built in functions has a number of UX issue we would like to address with a redesign of this section:

• The table makes the page long and hard to navigate
  • This makes the DOM slow to load, and slow to scroll on poorer performing machines.
• It is hard to show examples next to function reference in the tables, since there is some 'pressure' in a table layout to keep rows short.
  • In addition it'd be nice to have testable examples that can run in CI, at the moment we have a number of examples here which are not tested / linted but are featured prominently in the docs.
• Filtering the table is not possible, for example filtering by SDK, version availability, deprecated etc. (we might need to make some updates to builtin_metadata.json to support this)
• It's cumbersome to link directly to functions, as we have to use anchors on a huge page and manually generate the anchors in the table component.

First step: get some mockups / sketches of how solutions for these issues might look and post them here.

Some proposed improvements to scope out:

• Filterable table, something Regal does: https://docs.styra.com/regal/rules, but with more dropdowns and type to filter type selects since we have many categories.
• Section pages showing all builtins for that section in a table.
• Individual pages for single functions. Some will be sparse, but others like http.send have more than enough for their own page. (and it'd be best to be consistent)

[sky3n3t]

I'd like to work on this

[charlieegan3]

https://github.com/open-policy-agent/opa/pull/7686 and https://github.com/open-policy-agent/opa/pull/7690 are related to this issue, the early steps which set the groundwork for more docs examples down the line

[charlieegan3]

https://github.com/open-policy-agent/opa/pull/7690 has been merged, so now we have the same standard format for all existing builtin examples.

[charlieegan3]

https://github.com/open-policy-agent/opa/pull/7704 has also been merged now, it shows a nice built-in search on the policy reference page. We're planning to use this as the basis to a reduced amount of detail on the page, while still letting users explore the different functions.

[sky3n3t]

OUTDATED

Example of a test structure using token sign, still very cluttered but it is

Can be found here if you build the docs with this repo

[sky3n3t]

flex row layout in a modal

Can be found here if you build the docs with this repo

[Parsifal-M]

• Individual pages for single functions. Some will be sparse, but others like http.send have more than enough for their own page. (and it'd be best to be consistent)

Heya 👋

Are you thinking something like this?

└── Policy Reference
    └── Built In Functions
        ├── Comparison
        ├── Numbers

I think that would be nice 😄 then maybe in Built In Functions just a table with the sub-pages for a more high level "what I am looking for" which would link to the subpage

Use Case	Notes
Comparison	Functions for comparing things
Numbers	Functions for numbers

Or something like that 😅 just throwing some ideas out 👏

[charlieegan3]

Thanks for the feedback Peter! I think the plan at the moment is yes, that we'll need to have some kind of Category page too.

Little more context to this issue here: https://openpolicyagent.slack.com/archives/C02L1TLPN59/p1750345039271949

[charlieegan3]

We're merging this too, https://github.com/open-policy-agent/opa/pull/7724 which is related to breaking out category pages.

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days. Although currently inactive, the issue could still be considered and actively worked on in the future. More details about the use-case this issue attempts to address, the value provided by completing it or possible solutions to resolve it would help to prioritize the issue.

[anderseknert]

@charlieegan3 anything left to do here?

[charlieegan3]

Hmm, there are other things I'd like to do here, but I think we've made some good improvements here. Let's close for now and see if there are user feedback submissions with more information to guide on the next steps.