docs: improve functions reference (#1049)

Co-authored-by: Yiran <cuiyiran3@gmail.com>

.github/workflows/linter.yml

@@ -19,3 +19,5 @@ jobs:
         config_file: .markdownlint.yaml
     - name: Check typos
       uses: crate-ci/typos@master
+      with:
+        config: .typo.toml

.typo.toml

@@ -0,0 +1,2 @@
+[files]
+extend-exclude = ["*/**/df-functions.md"]

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to GreptimeDB Docs
 
-## File Structure
+## File structure
 
 This project uses markdown files to generate a documentation website.
 All markdown files are located in the `docs` directory.
@@ -11,27 +11,40 @@ For example, `/docs/v0.4` contains the documentation for GreptimeDB v0.4.
 It should match the current document structure.
 You need to use `-` and lowercase letters in markdown file names so that `summary.yml` can recognize these file names.
 
-### Document Localization
+### Document localization
 
 - The localized documentation is located in the `/docs/xx` directory, where `xx` is the language code.
 - The `summary-i18n.yml` file in the `/docs/xx` directory defines the navigation of the localized documentation website.
 The content in `summary-i18n.yml` should be the localized name of the relative directory.
 If you add a new directory in `/docs/xx`, remember to update `summary-i18n.yml`.
 
-## Links
+### Links
 
-- Use relative paths for internal links whenever possible.
 - Reference files placed in `public` using root absolute path - for example, `public/icon.png` should always be referenced in source code as `/icon.png`.
 
-## Style Guide
+## Write documentation
+
+### Update `df-functions.md`
+
+Use the following command to generate `/en/reference/sql/functions/df-functions.md`:
+
+```shell
+ruby misc/update_functions.rb [nightly | v0.x]
+```
+
+Then copy the English content to the corresponding localized file and translate it.
+
+## Style guide
+
+### Image style
 
 Please use [`example.drawio.svg`](docs/example.drawio.svg) as a template for drawing diagrams.
 You can install the Draw.io Integration for VS Code and create a new diagram from the template.
 
 If there is no suitable graphics, you can use other graphics,
 but the colors should be consistent with the template.
 
-## Markdown Lint
+### Markdown lint
 
 We use [markdownlint-cli](https://github.com/DavidAnson/markdownlint) to check
 format of markdown files. You can do it locally with:
@@ -55,7 +68,7 @@ pnpm run dev
 
 You can also use `pnpm run build` to check dead links.
 
-### Preview the Localized documentation
+### Preview the localized documentation
 
 To preview the documentation in a specific language,
 add a new file called `.env` to the root directory and include the `VITE_LANG=xx` environment variable,
@@ -68,7 +81,7 @@ VITE_LANG=zh
 
 Then start a local server with `pnpm run dev`.
 
-## PR Title Check
+## PR title check
+
+We use [action-semantic-pull-request](https://github.com/amannn/action-semantic-pull-request) to ensure that PR titles follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
 
-We require pull request title to start with [these
-keywords](https://github.com/GreptimeTeam/docs/blob/main/.github/pr-title-checker-config.json#L7C1-L7C1)

docs/misc/update_functions.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/ruby
+## A script to update functions in nightly references
+## Usage: ruby misc/update_functions.rb [nightly | v0.x]
+# encoding: utf-8
+require 'net/http'
+
+scalar_functions = {
+  :name => "DataFusion Scalar Functions",
+  :url => "https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/scalar_functions.md"
+}
+agg_functions = {
+  :name => "DataFusion Aggregate Functions",
+  :url => "https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/aggregate_functions.md"
+}
+window_functions = {
+  :name => "DataFusion Window Functions",
+  :url => "https://raw.githubusercontent.com/apache/datafusion/main/docs/source/user-guide/sql/window_functions.md"
+}
+
+## Apache DataFusion functions
+datafusion_functions = [scalar_functions, agg_functions, window_functions]
+
+
+def process_headlines(line)
+  ## Add a level of headlines
+  if line =~ /^\s*(#+)\s/
+    replacement = "#{$1}#"
+    ## We don't want to render the function names in right menu bar
+    replacement += "#" if replacement.length >= 4
+    line.gsub! $1, replacement
+  end
+  line
+end
+
+def fix_links(line)
+  ## Fix link: #a_b_c -> #a-b-c
+  line.gsub!(/(#[a-zA-Z0-9_]+)\)/) { |match| match.gsub("_", "-") }
+  ## Fix link: a_b_c.md -> #a-b-c
+  line.gsub!(/\]\(([a-zA-Z0-9_]+\.md)\)/) { |match|
+    match.gsub("_", "-").gsub(".md", "").gsub("](", "](#")
+  }
+
+  line
+end
+
+
+File.open("temp.md", "w") do |f|
+  f.puts("# DataFusion Functions\n\n")
+  f.puts("This page is generated from the Apache DataFusion project's documents:")
+
+  for doc in datafusion_functions
+    name = doc[:name]
+    url = doc[:url]
+    markdown = "  * [#{name}](#{url})"
+    f.puts markdown
+  end
+
+  f.puts
+
+  for doc in datafusion_functions
+    uri = URI(doc[:url])
+    markdown = Net::HTTP.get(uri).force_encoding(Encoding::UTF_8)
+
+    lines = markdown.split(/\n/)
+
+    lines.map! do |line|
+      line = process_headlines(line)
+      line = fix_links(line)
+      line
+    end
+
+    f.puts lines.join("\n")
+  end
+end
+
+target = ARGV[0] || "nightly"
+
+File.rename "temp.md", "#{target}/en/reference/sql/functions/df-functions.md"
+
+puts "#{target}/en/reference/sql/functions/df-functions.md updated!"

docs/nightly/en/faq-and-others/faq.md

@@ -145,7 +145,7 @@ Of course, please use the `compact_table` function:
 select compact_table("test");
 ```
 
-There are many [administration functions](/reference/sql/functions#admin-functions) for database management.
+There are many [administration functions](/reference/sql/functions/overview#admin-functions) for database management.
 
 ### Can GreptimeDB be used to store logs?