zhangshenghang opened a new pull request, #13289:
URL: https://github.com/apache/seatunnel/pull/13289
Yes, I am contributing to Apache SeaTunnel.
## What documentation issues were found
While auditing the file connector family
(Cos/Bos/Obs/OssJindo/Oss/S3/Smb/Gcs/Ftp) against the shared connector code, I
found that a large set of user-facing options that live in the shared base
classes were documented on some file connector pages but missing entirely from
sibling pages, in both English and Chinese:
- **Source pages**: the whole sync/discovery/backup family
(`discovery_mode`, `scan_interval`, `start_mode`, `sync_mode`, `target_path`,
`target_hadoop_conf`, `update_strategy`, `compare_mode`,
`update_compare_parallelism`, `update_compare_bulk_threshold`,
`post_sync_action`, `backup_path`, `retention_max_age`,
`retention_check_interval`) was absent from the CosFile, BosFile, ObsFile and
OssJindoFile (en) pages, even though these options are read at runtime by the
shared base source code for all file connectors.
`enable_file_split`/`file_split_size`, `excel_use_header_line`,
`markdown_rag_metadata_enabled`, `pdf_rag_metadata_enabled` and (BosFile)
`null_format` were also missing from several pages.
- **Sink pages**: `schema_save_mode`/`data_save_mode`,
`enable_header_write`, `date_format`/`datetime_format`/`time_format`,
`merge_update_event`, `schema_evolution_enabled`, `csv_string_quote_mode`,
`sheet_max_rows`/`sheet_name`/`max_rows_in_memory`,
`xml_root_tag`/`xml_row_tag`/`xml_use_attr_format`,
`parquet_avro_write_*_int96`, and (ObsFile)
`encoding`/`filename_extension`/`tmp_path` were missing from several sink pages.
- **zh OssJindoFile page parity**: the Chinese page was far behind the
English one - it lacked most per-option explanation sections (`path`, `bucket`,
`access_key`, `access_secret`, `endpoint`, `read_columns`, delimiters,
partition parsing, date/time formats, `skip_header_row_number`, `schema`, excel
options, `file_filter_pattern` examples, compress codecs, encoding,
`null_format`, filter/CSV options, common options), the json/csv/text format
examples under `file_format_type`, all usage examples (orc/json/binary
transfer/filter file), and the sync/discovery family rows.
- **zh SftpFile page**: the `quote_char` and `escape_char` option
explanation sections documented in English were missing in Chinese.
## What was changed
- Added the missing option table rows (and the "Continuous Discovery"
section with a connector-specific example) to the affected pages, reusing the
exact wording already used by the reference pages (LocalFile/SftpFile/OssFile)
so the whole family stays consistent.
- Backfilled the missing Chinese sections/examples for OssJindoFile and
SftpFile so zh mirrors en.
- All option names, types and default values were verified against the code:
`connector-file-base` `FileBaseOptions` / `FileBaseSourceOptions` /
`FileBaseSinkOptions`, `seatunnel-api` `FormatOptions` (`date_format` family)
and `SinkConnectorCommonOptions` (`multi_table_sink_replica`). Continuous-mode
constraints (`sync_mode=update`, `file_format_type=binary` for non-local
filesystems) match the validation logic in
`ContinuousMultipleTableFileSourceSplitEnumerator`.
- Examples use each connector's real authentication options (e.g. CosFile
`secret_id`/`secret_key`/`region` with `cosn://` buckets, ObsFile
`access_key`/`secret_key`/`endpoint` with `obs://` buckets).
## Areas / files updated
29 files, ~1050 added lines:
-
`docs/{en,zh}/connectors/source/{CosFile,BosFile,ObsFile,OssJindoFile,OssFile}.md`
- missing source option rows + Continuous Discovery sections
-
`docs/{en,zh}/connectors/sink/{OssJindoFile,CosFile,BosFile,ObsFile,GcsFile,SmbFile,FtpFile,OssFile,S3File}.md`
- missing sink option rows
- `docs/zh/connectors/source/OssJindoFile.md` - backfilled option detail
sections, format examples, usage examples
- `docs/zh/connectors/source/SftpFile.md` - added missing
`quote_char`/`escape_char` sections
## English and Chinese docs
Both language versions were checked; the same gaps existed on both sides and
were fixed in parallel with matching wording (zh wording reuses the sentences
already used for the same options on zh LocalFile/OssFile pages).
## Duplicate PR check (last 7 days)
I searched all PRs created since 2026-11-09 before opening this one:
- #13234, #13258, #13274 (connector doc fixes) - cover
Doris/StarRocks/TDengine/Milvus/Clickhouse/Redis/CDC etc., not the file
connector family; no overlap.
- #13282 - touches `docs/en/connectors/source/OssJindoFile.md`, but only
fixes a scheduling-claim wording issue in the Description; this PR adds missing
option rows and sections to that file, no content overlap.
- #13284 - fixed FtpFile/LocalFile *source* examples and type cells; this PR
touches FtpFile *sink* pages and adds different content, no overlap.
- #13270 - rewrites TextChunk transform docs; unrelated.
## Verification
- Ran a structural link/anchor checker over all 1114 md files in `docs/en` +
`docs/zh`: no new broken links introduced (result set unchanged from before the
change).
- Verified all modified markdown tables have consistent column counts (0
mismatches).
- Re-ran the option-gap checker after the changes: all previously missing
rows are now documented, with no remaining gaps for the file connector family.
- A full docusaurus site build was not run locally because the website build
tooling is not part of this repository (docs/ contains only markdown +
sidebars.js); the structural checks above were used instead.
--
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]