zhangshenghang opened a new pull request, #12331:
URL: https://github.com/apache/seatunnel/pull/12331
## Purpose of this PR
This PR fixes a batch of real documentation defects found by cross-checking
the docs against the connector source code, plus a full broken-link/anchor
sweep of `docs/en` and `docs/zh`. 43 documentation files are updated (en + zh
kept in sync for every fix).
## What documentation issues were found
**Option names / defaults inconsistent with code (verified against
`Options.key(...)` definitions):**
1. **Kafka source `is_native`** – listed in the options table (en + zh) but
this option never existed anywhere in the connector code (confirmed via `git
log -S 'Options.key("is_native")'` across all history). It was re-introduced by
a merge conflict resolution error after PR #11335 had already removed it. Row
removed.
2. **Persistiq `content_json`** – the options table says `content_json`, but
the code (`HttpSourceOptions`) and the document's own examples use
`content_field`. Renamed in table and detail heading (en + zh).
3. **HugeGraph sink defaults** – table said `batch_failure_fallback = true`
and `max_insert_errors = 500`, while `HugeGraphOptions` defines `false` and `0`
(the en description text even said "Default 0" while the table column said
500). Fixed (en + zh).
4. **IoTDBv2 sink defaults** – `max_retries`, `retry_backoff_multiplier_ms`,
`max_retry_backoff_ms` are `noDefaultValue()` in code but documented as `0`.
Changed to `-` (en + zh).
5. **File connector `field_delimiter`** – source ObsFile/OssFile docs only
listed the deprecated legacy name `delimiter` (code: `field_delimiter` with
`withFallbackKeys("delimiter")`); renamed to `delimiter/field_delimiter` with
the deprecation note, matching S3File/HdfsFile docs. Sink file docs (BosFile,
CosFile, FtpFile, HdfsFile, LocalFile, OssFile, OssJindoFile, SftpFile, S3File,
zh BosFile, zh OssJindoFile) documented the default as `'\001' for text and ','
for csv`, but since #9034 the sink default is a single `'\001'` for all
formats. Aligned with code and with sink ObsFile docs.
**Broken links / anchors (found via scripted sweep of all 1035 md files):**
6. `docs/zh/connectors/connector-faq.md` – 10 links pointed to `#faq`, but
the zh target docs use `## 常见问题` headings. Fixed to `#常见问题`.
7. `connector-faq.md` (en + zh) JDBC Sink link pointed to `#faq`, but
`Jdbc.md` has no FAQ section – retargeted to the existing `## Troubleshooting`
/ `## 故障排查` section.
8. `edge-agent` docs (en + zh: configuration, faq, input-configuration,
output-configuration, quick-start) – 18 references to stale anchors
`#identity-file-edge-agentid` / `#身份文件edge-agentid`,
`#sqlite-persistence-files` / `#sqlite-持久化文件`, `#console-local-test-no-engine`,
`#production-setup-with-engine` and zh equivalents, all retargeted to the
current heading slugs.
9. `docs/zh/engines/zeta/log-analysis-with-ai.md` – linked to
`rest-api-v2.md#get-logs-from-all-nodes`, but the zh REST API doc uses the
heading `获取所有节点日志内容`. Fixed.
10. `docs/zh/connectors/source/{FakeSource,Hbase,Typesense}.md` and
`docs/zh/connectors/{source,sink}/{BosFile,GcsFile,OssJindoFile}.md` – English
anchors (`#how-to-declare-type-supported`, `#multimodal`) pointing at zh docs
whose headings are Chinese; retargeted to the actual zh slugs (`#如何声明支持的类型`,
`#多模态multimodal`).
11. `docs/en/connectors/source/ObsFile.md` – copy-paste bug in the tips
section: `<span id="schema"> read_columns </span>` (wrong id) and `<span
id="common_options ">` (trailing space breaks the id); both fixed.
12. `docs/en/introduction/configuration/config-encryption-decryption.md` –
in-page link contained raw spaces (`(#How to implement user-defined encryption
and decryption)`), which cannot resolve; replaced with the real heading slug.
## Which areas/files were updated
- `docs/en/connectors/**` and `docs/zh/connectors/**` (Kafka, Persistiq,
HugeGraph, IoTDBv2, file connectors, connector-faq) – 32 files
- `docs/{en,zh}/edge-agent/**` – 10 files
- `docs/zh/engines/zeta/log-analysis-with-ai.md`,
`docs/{en,zh}/introduction/**` – 3 files (multimodal zh anchor file included)
In total: **43 files changed, 78 insertions, 80 deletions**.
## Were both English and Chinese docs checked?
Yes. Every content fix above was applied to both language versions wherever
the same wrong content existed, and the anchor sweep covered all of `docs/en`
and `docs/zh`.
## How duplicate PRs were checked
`gh pr list --repo apache/seatunnel` was checked for open and merged PRs
from the last 7 days with `Docs` in the title. Found: #12328 (IMap persistence
examples), #12276 (adds the missing Http-Linear English doc – untouched here;
`Http-Linear.md` en is the only en/zh file-set gap and it is already handled
there), #12213/#12214 (Zeta benchmark & contribution guides). None of them
overlap with the fixes in this PR.
## How the change was verified
- A scripted link check over all 1035 md files (relative link targets must
exist): 0 broken files (4 pre-existing false positives inside code blocks in
`dynamic-compile.md`, untouched).
- A scripted anchor check (heading slugs incl. `<span id>`/`<a name>`,
in-page and cross-file): 0 broken anchors after this change (was 74).
- A scripted cross-check of every doc options table against
`Options.key(...)` definitions and `defaultValue(...)`/constants extracted from
`seatunnel-connectors-v2` / `seatunnel-transforms-v2` / `seatunnel-api` source:
all options renamed/fixed in this PR now resolve; every changed default matches
the code.
- Verified no control characters or malformed table rows were introduced
(`git diff` reviewed per hunk).
- No build/test run: this PR touches only Markdown documentation, so a full
Maven build would not exercise the changed files.
--
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]
