[
https://issues.apache.org/jira/browse/FLINK-23804?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Ramin Gharib updated FLINK-23804:
---------------------------------
Description:
The current documentation for built-in functions does not scale well. Tables,
even in sections, become very hard to read with many entries, and there is very
little space for proper signatures, details, or examples.
We should restructure this page such that functions are not grouped into tables
but rather their own sections. This could possibly involve splitting the page
into several pages (per category).
In the end, we should have a documentation that lists signatures properly,
including return types, multiple signatures, signatures for both Table API and
SQL, allows for detailed descriptions of each function and various examples in
both APIs.
h3. Plan
Discussed on the dev list:
https://lists.apache.org/thread/3w04cd3w162k7hvko52of7vrvmjm4cjs
Screenshots of a local prototype, all in [this
folder|https://drive.google.com/drive/folders/123rKBt0ESz5Wn5VSlCcQF3hxJuwtf3Q9]:
* [REGEXP_EXTRACT function
page|https://drive.google.com/file/d/1LCE4CqTn2AYl90XGN2WXwnUi9JBRqnDw/view]
* [Sidebar with the function
categories|https://drive.google.com/file/d/1cde0G55BLDVT-17caaXVwBHM65jWuVOQ/view]
* [A-Z overview of all
functions|https://drive.google.com/file/d/19eQRVg_VRUS4kRQKBASLWcaKqijSZwjG/view]
Steps:
# FLINK-41315: add the new structure. One page per function with a fixed set of
sections, generated from YAML, a sidebar that groups the function pages by
category, and an A-Z overview at the current URL. REGEXP_EXTRACT is converted
first.
# Convert the functions category by category. Each conversion rechecks every
function against its implementation and adds missing examples. Category
sub-tasks are added as the conversion starts.
# FLINK-41316: publish each function page as Markdown and add an llms.txt index.
was:
The current documentation for built-in functions does not scale well. Tables,
even in sections, become very hard to read with many entries, and there is very
little space for proper signatures, details, or examples.
We should restructure this page such that functions are not grouped into tables
but rather their own sections. This could possibly involve splitting the page
into several pages (per category).
In the end, we should have a documentation that lists signatures properly,
including return types, multiple signatures, signatures for both Table API and
SQL, allows for detailed descriptions of each function and various examples in
both APIs.
> Restructure documentation of built-in functions
> -----------------------------------------------
>
> Key: FLINK-23804
> URL: https://issues.apache.org/jira/browse/FLINK-23804
> Project: Flink
> Issue Type: Improvement
> Components: Documentation, Table SQL / API
> Reporter: Ingo Bürk
> Assignee: Ramin Gharib
> Priority: Minor
>
> The current documentation for built-in functions does not scale well. Tables,
> even in sections, become very hard to read with many entries, and there is
> very little space for proper signatures, details, or examples.
> We should restructure this page such that functions are not grouped into
> tables but rather their own sections. This could possibly involve splitting
> the page into several pages (per category).
> In the end, we should have a documentation that lists signatures properly,
> including return types, multiple signatures, signatures for both Table API
> and SQL, allows for detailed descriptions of each function and various
> examples in both APIs.
> h3. Plan
> Discussed on the dev list:
> https://lists.apache.org/thread/3w04cd3w162k7hvko52of7vrvmjm4cjs
> Screenshots of a local prototype, all in [this
> folder|https://drive.google.com/drive/folders/123rKBt0ESz5Wn5VSlCcQF3hxJuwtf3Q9]:
> * [REGEXP_EXTRACT function
> page|https://drive.google.com/file/d/1LCE4CqTn2AYl90XGN2WXwnUi9JBRqnDw/view]
> * [Sidebar with the function
> categories|https://drive.google.com/file/d/1cde0G55BLDVT-17caaXVwBHM65jWuVOQ/view]
> * [A-Z overview of all
> functions|https://drive.google.com/file/d/19eQRVg_VRUS4kRQKBASLWcaKqijSZwjG/view]
> Steps:
> # FLINK-41315: add the new structure. One page per function with a fixed set
> of sections, generated from YAML, a sidebar that groups the function pages by
> category, and an A-Z overview at the current URL. REGEXP_EXTRACT is converted
> first.
> # Convert the functions category by category. Each conversion rechecks every
> function against its implementation and adds missing examples. Category
> sub-tasks are added as the conversion starts.
> # FLINK-41316: publish each function page as Markdown and add an llms.txt
> index.
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
