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 >>> >>
