zhangshenghang opened a new pull request, #12423:
URL: https://github.com/apache/seatunnel/pull/12423
## Purpose of this pull request
This PR fixes a batch of real documentation inaccuracies found by auditing
docs against the actual code (option definitions, factory `optionRule()`s,
server config parsers and CLI argument classes), and syncs missing Chinese
content. All findings were verified against source before editing.
## What documentation issues were found
### Transform docs (`docs/{en,zh}/transforms/`)
- **sql.md**: `plugin_input` / `plugin_output` were marked required, but
`SQLTransformFactory.optionRule()` only requires `query`.
- **llm.md**: `QIANFAN` was missing from the `model_provider` list although
implemented (`LLMTransform` + factory conditional rule); `api_key` was marked
unconditionally required but is only required for
OPENAI/DOUBAO/MICROSOFT/QIANFAN; `secret_key` / `oauth_path` (required for
QIANFAN) and five real options (`process_batch_size` 100,
`model_retry_max_attempts` 1, `model_retry_backoff_ms` 1000,
`model_retry_max_backoff_ms` 10000, `model_request_timeout_ms` 20000) were
undocumented.
- **embedding.md**: `dimension` default shown as `-` although code default
is 2048 (zh was already correct); a "TThe" typo; `api_key` / `secret_key`
marked unconditionally required but are conditional per provider per
`EmbeddingTransformFactory.optionRule()`.
- **filter-rowkind.md**: `include_kinds` / `exclude_kinds` marked required
although `optionRule()` defines them as an exclusive (exactly-one) pair; body
text already said "only one of".
- **field-mapper.md**: changelog said "Add Copy Transform Connector".
### Zeta engine docs (`docs/{en,zh}/engines/zeta/`)
- **engine-jar-storage-mode.md**: documented key
`connector-jar-storage-enable` does not exist — the parser only accepts
`enable` under `seatunnel.engine.jar-storage`; examples also lacked the
`seatunnel: engine:` parents, so the feature would silently never enable.
- **hybrid-cluster-deployment.md / separated-cluster-deployment.md**:
`coordinator-service` example missing `seatunnel: engine:` nesting (parser only
reads it under `seatunnel.engine`); `max-thread-num` mis-described as "max job
count" — it is the coordinator thread pool max size (`ServerConfigOptions` /
`CoordinatorService`).
- **user-command.md**: documented CLI help omitted six real client options
(`--set-job-id`, `--checkpoint-overview`, `--checkpoint-history`,
`--checkpoint-history-pipeline`, `--checkpoint-history-limit`,
`--checkpoint-history-status`, from `ClientCommandArgs.java`); example cluster
output used Hazelcast 5.3.0 and port 5701 instead of the shaded 5.1 and
SeaTunnel default 5801 (`config/hazelcast.yaml`).
- **telemetry.md**: metrics endpoints are served through the Hazelcast REST
API which ships **disabled** (`config/hazelcast.yaml` `rest-api.enabled:
false`) — added a prerequisite note; also fixed a malformed metrics table row
(stray trailing pipe, pre-existing).
- **stain-trace.md**: documented the backward-compat alias
`stain-trace-sample-interval` as the primary option; canonical key is
`stain-trace-sample-rate` (`ServerConfigOptions`).
### Connector docs (`docs/{en,zh}/connectors/`)
- **Maxcompute.md (sink)**: removed `datetime_format` option (row + section)
— no such option exists in `connector-maxcompute`.
- **SelectDB-Cloud.md (sink)**: `password` and `selectdb.config` marked
Required but the factory rule marks both optional; `sink.buffer-size` default
labeled "(1MB)" is actually 10MB.
- **SqlServer-CDC.md (source)**: `connect.timeout` renamed to the real key
`connect.timeout.ms` (default 30000), consistent with all sibling CDC docs.
- **StarRocks.md (sink)**: `batch_max_rows` / `batch_max_bytes` types were
swapped (int/long per `StarRocksSinkOptions`).
- **Paimon.md (source)**: FAQ referenced nonexistent `paimon.catalog.type`;
real key is `catalog_type`.
- **AmazonDynamoDB.md (sink)**: `multi_table_sink_replica` default `-` → `1`
(`SinkConnectorCommonOptions`).
- **MySQL-CDC.md (source)**: `startup.specific-offset.skip-events` /
`skip-rows` have no default in code (only applied when explicitly configured) —
default `0` → `-`.
### zh content parity
- **docs/zh/connectors/sink/Doris.md**: added three example sections present
in en since #11796 but missing in zh: Custom SQL Pre-processing, CDC With
Schema Change, Multiple table (2 examples).
- **docs/zh/engines/zeta/rest-api-v2.md**: added the missing
checkpoint-history Field Description table.
## Areas / files updated
38 files: transforms (en+zh × 5), engines/zeta (en+zh × 6), connectors
sink/source (en+zh × 7), plus zh Doris and zh rest-api-v2.
## Both English and Chinese docs checked?
Yes. Every en/zh pair was fixed in lockstep where both had the issue;
zh-only gaps (Doris examples, rest-api-v2 field table) were filled from en.
## Duplicate check (last 7 days)
Checked open/merged doc PRs before submitting: #12331 (merged, anchor/option
fixes — no overlap), #12347 (open, option defaults + zh Splunk — no overlap
with this PR's changes; my zh Doris change adds example sections, not the
default-value row it fixes), #12378 (open, feature-checklist sync + doc
relocation — no overlap; my zh StarRocks change fixes option types, it flips a
checkbox), #12409 (open, zh translation sync — no overlap; my SqlServer-CDC
change fixes the option table row it doesn't touch). No already-covered issue
is re-fixed here.
## How the change was verified
- Each fix was confirmed against the Java/config source (option keys,
`defaultValue`, `OptionRule` required/optional/conditional/exclusive wiring,
YAML DOM parser keys, CLI `@Parameter` definitions, shaded Hazelcast version).
- Scripted structural checks over all 38 changed files: markdown table
column consistency, balanced code fences, no duplicate section headings in
edited areas, and YAML parse validation of the corrected config examples.
- No docs lint/build workflow exists in this repo for docs/ (Docusaurus site
config lives outside), so no further automated check was run; full Maven verify
was skipped as this PR contains no code changes.
--
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]
