raminqaf commented on code in PR #29864: URL: https://github.com/apache/flink/pull/29864#discussion_r4601099803
########## docs/README.md: ########## @@ -283,3 +285,49 @@ Renders a link to a file in the Apache Flink Python Documentation. ``` Renders a link to the apache flink download page. + +## Built-in function pages + +Pages for built-in SQL functions live under `content/docs/sql/built-in-functions/<category>/`. They aren't written in Markdown. A content adapter generates each page, in English and Chinese, from one YAML file in `data/functions/`. + +### Adding a function + +1. Add `data/functions/<category>/<name>.yml`. `<category>` is the directory of the category under `content/docs/sql/built-in-functions/`, such as `regular-expressions`. `<name>` is the function name in lower case, such as `regexp_extract`, and the page is served at `<category>/regexp-extract/`. Use `data/functions/regular-expressions/regexp_extract.yml` as the reference for the fields. +2. Add a row for the function to its category in `data/sql_functions.yml` and `data/sql_functions_zh.yml`. Keep the rows in alphabetical order of the function name, the order of the pages in the sidebar. Give it `sql`, `table` and `page: regexp-extract`, without a `description`. The table shows the function's name, links it to the page and shows the page's summary. +3. Build the docs as described above and check the page in both languages. A broken `ref` fails the build, locally and in CI. + +The Chinese page renders the same YAML, so the English text is its placeholder until someone translates it. If you aren't a native Chinese speaker, don't translate: add no Chinese file and leave the translation to native speakers. A translation goes in `data/functions_zh/<category>/<name>.yml`, and the fields it sets replace the English ones. Review Comment: Good point, I'll open a ticket for the Chinese text and link it on FLINK-41433. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
