Hi Xiqian, Thanks for the +1! I like the idea of the overview page for the easier search. I will include it.
Cheers, Ramin On Thu, Oct 29, 2026 at 6:31 AM Xiqian YU <[email protected]> wrote: > Hi Ramin, > > Thanks for the proposal! +1 to reorganizing the built-in function docs. > The proposed layout looks much neater and cleaner. > > One small concern is the search experience. With the current single-page > layout, I can use the browser’s built-in search (Cmd+F) to quickly find the > function I’m looking for. This would be less convenient once the content is > split across multiple pages, as I find Hugo Book’s built-in search a bit > harder to use. > > Would it make sense to include an overview page listing all built-in > functions in alphabetical order, with links to their individual pages, > similar to Spark SQL [1]? This would preserve a convenient way to browse > and search the full list. > > Best regards, > Xiqian > > [1] https://spark.apache.org/docs/latest/api/sql/index.html > > > Ramin Gharib <[email protected]> 於 2026年10月28日 晚上11:15 寫道： > > > > 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 > >>> > >> > >
