Hi Gustavo, Thanks for the +1 and the suggestions.
1. Good idea, I'll add it to the proposal. 2. Agreed, that's the plan. It also lets CI run the examples (optionally), because a test can read them straight from the YAML. Building pages from data needs Hugo's content adapters, which arrived in Hugo 0.126, and the docs currently pin 0.124.1. So we either upgrade Hugo or let a small script generate the pages. One open choice is one YAML file per function or one per category. 3. I'd add them during the migration rather than hide the section. A rough count finds an example in only about 91 of the 306 entries. Many functions already have test cases in the function ITCases, so the examples can start from those. Once the examples live in YAML, (optionally) CI can run them against the implementation and require at least one per function, so the gap doesn't come back. Cheers, Ramin On Wed, Oct 28, 2026 at 3:31 PM Gustavo de Morais <[email protected]> wrote: > Hi Ramin, > > Thanks for picking this up, +1. Having a nicer UX for docs has been a long > standing wish and makes sense. Some suggestions and questions: > > 1. Also publish each function page as plain Markdown, plus an llms.txt that > indexes them. Hugo supports extra output formats, so this should be cheap. > 2. Keep the function data in YAML, with one field per section (syntax, > arguments, returns, examples) instead of a free-form description. A single > template then renders every page with the same sections, as HTML and > Markdown. > 3. We have built-in functions with no examples. Do you plan to add some > examples for those as part of this or will the pages just hide the examples > session? > > Kind regards, > Gustavo > > On Wed, 28 Oct 2026 at 14:57, Ramin Gharib <[email protected]> wrote: > > > Hi all, > > > > I'd like to restructure the built-in functions page [1]. It lists 306 > > functions and operators as table rows on a single page, each with a > > free-form description. Arguments, return values, NULL behavior and errors > > are hard to find. > > > > The proposal picks up FLINK-23804 [2]: > > - Each function gets its own page with the same sections: syntax for SQL > > and the Table API, arguments, returns, usage notes and examples. > > - The sidebar groups the function pages by category, and each category > > folds open and closed. > > > > The screenshots [3] show REGEXP_EXTRACT and the sidebar in the new > layout, > > built locally with the current docs theme. > > > > I'd move one category per PR. Moving the existing entries is mostly > > mechanical, so I'd use AI assistance and fill in the AI disclosure in the > > PR template. > > > > I would be interested in your feedback on this idea. > > > > Cheers, > > Ramin > > > > [1] > > > > > https://nightlies.apache.org/flink/flink-docs-release-2.4/docs/sql/functions/built-in-functions/ > > [2] https://issues.apache.org/jira/browse/FLINK-23804 > > [3] > > https://drive.google.com/drive/folders/123rKBt0ESz5Wn5VSlCcQF3hxJuwtf3Q9 > > >
