pingcap / pingcap/docs

Implement SQL formatter into the docs pipeline

Open
#13,031 6 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

2024-tidb-docs-dash type/enhancement
Dominant language
Python
Stars
617
Forks
724
Avg merge
2d 10h
Merged PRs (30d)
223

Description

Change Request

  1. Describe what you find is inappropriate or missing in the existing docs.

    It would be better to have SQL code be more readable by default and be stacked as opposed to all one line.

    For example, the line:

    SELECT l_orderkey, MAX(L_COMMENT), MAX(L_SHIPMODE), MAX(L_SHIPINSTRUCT), MAX(L_SHIPDATE), MAX(L_EXTENDEDPRICE) FROM lineitem GROUP BY l_orderkey HAVING SUM(l_quantity) > 314;
    

    Would be more readable as:

    SELECT 
          l_orderkey, 
          MAX(L_COMMENT), 
          MAX(L_SHIPMODE), 
          MAX(L_SHIPINSTRUCT), 
          MAX(L_SHIPDATE), 
          MAX(L_EXTENDEDPRICE) 
    FROM lineitem 
    GROUP BY l_orderkey 
    HAVING SUM(l_quantity) > 314;
    
  2. Describe your suggestion or addition.

    Try and put something like https://sqlfum.pt/ into the docs pipeline to automatically:

    • Fix the case for SQL keywords (e.g. "insert" → "INSERT")
    • Convert to multi-line
  3. Provide some reference materials (such as documents and websites) if you could.

    https://github.com/mjibson/sqlfmt (which is https://wasm.sqlfum.pt/ )
    https://sqlfmt.com/
    https://www.salvis.com/blog/2020/08/28/formatting-sql-code-blocks-in-markdown-files/

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files, tests, or pipeline entry points are named. Start by locating the docs pipeline and review the linked sqlfmt, SQL Fumpt, and Markdown references; done should mean SQL blocks are automatically reformatted with uppercase keywords and multiline layout.

Written by the indexing model from the issue text.

Assessment

Tech stack
sql
Domain
build-system, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.