boluor opened a new pull request, #3784:
URL: https://github.com/apache/doris-website/pull/3784
## Summary
**Demo PR** proposing a small authoring convention for
`sql-manual/sql-functions/` doc pages, applied here to `array-filter.md` (EN +
ZH) as a concrete example. Looking for maintainer feedback on the shape before
scaling to other pages.
## The convention in one paragraph
Inside `## Examples`, each runnable example becomes a numbered pair of
fenced blocks:
````
```sql {example="N"} ← SQL to execute (copy button, runnable)
```result {example="N"} ← expected output (no copy)
```error {example="N"} ← expected error (no copy)
````
One-time fixture data goes in ` ```sql {setup} `. The `## Syntax` block
stays unchanged. EN and ZH share the same `example="N"` numbers, so
cross-language drift becomes mechanically detectable.
## Why
1. **Machine-verifiable.** A doc-verify tool can match every `sql
{example="N"}` to its `result|error` block by ID — zero heuristic guessing
about where SQL ends and output begins.
2. **EN/ZH consistency.** Same example numbers across languages → missing or
drifted examples are detectable by tooling, not by manual review.
3. **UX.** Readers copy SQL safely; expected output stays visually distinct
and is not mis-copied as input.
4. **Backward compatible.** Pages that don't use the convention keep working
exactly as today. It's opt-in per page.
## What's in this PR
Just `array-filter.md`, both languages:
-
`versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md`
-
`i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md`
### Before / after (one example)
Before:
````markdown
Using lambda expression to filter elements in double_array greater than or
equal to 3:
```sql
SELECT array_filter(x -> x >= 3, double_array) FROM array_filter_test WHERE
id = 1;
+------------------------------------------+
| array_filter(x -> x >= 3, double_array) |
+------------------------------------------+
| [3.3, 4.4, 5.5] |
+------------------------------------------+
```
````
After:
````markdown
**Example 1** — Lambda over a DOUBLE array column: keep elements `>= 3`.
```sql {example="1"}
SELECT array_filter(x -> x >= 3, double_array) FROM array_filter_test WHERE
id = 1;
```
```result {example="1"}
+------------------------------------------+
| array_filter(x -> x >= 3, double_array) |
+------------------------------------------+
| [3.3, 4.4, 5.5] |
+------------------------------------------+
```
````
### Bundled fix
The original EN page had a code block at line ~164 with only the result
table (the `SELECT` statement was missing). Reconstructed the `SELECT` from the
result column header — it is now Example 9.
## Verification
Ran every example on a single-node Apache Doris 4.1.1 cluster:
- **EN**: 20 pass / 0 fail / 1 not_checked (Syntax illustrative block)
- **ZH**: 20 pass / 0 fail / 1 not_checked
- All 4 error examples carry `kind=error` expected output and match the
actual `errCode = …, detailMessage = …` from Doris, after stripping
environment-specific IP prefixes.
## Rendering
Without any theme changes, docusaurus renders:
- `sql` fences with syntax highlight + copy button (default behavior,
unchanged)
- `result` and `error` fences as plain code blocks (Prism doesn't know these
languages, so no highlight; copy button still present by default)
The convention's full UX (red-styled `error` block, no copy on
`result`/`error`) needs a small theme override, which would be a separate
follow-up PR. **This PR does not require any theme change** — the markdown is
valid and renders correctly today.
## Asking for
- Is the convention shape (`{example="N"}`, three fence types) OK?
- Where should the full authoring spec live? Suggestions:
`.docs-governance/` or `doc-tools/`. A separate spec-doc PR can follow.
- If approved, follow-ups will convert other `array-*` function pages in the
same style.
Co-authored-by: doris-verify
<https://github.com/apache/doris-website/pull/3781>
--
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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
