zhangshenghang opened a new pull request, #12621:
URL: https://github.com/apache/seatunnel/pull/12621
## Purpose of this PR
This PR fixes a batch of real documentation problems found by cross-checking
the docs against the connector source code on the current `dev` branch.
## What documentation issues were found
1. **Http-Linear docs are unreachable from the site (wrong path, added by
#12270).** The connector documentation was committed to the legacy path
`docs/en/connector-v2/source/Http-Linear.md`. The docs sidebar autogenerates
from `docs/{en,zh}/connectors/{source,sink}`, so the page is not linked
anywhere, and every other connector lives under `docs/{en,zh}/connectors/`. The
legacy `docs/en/connector-v2/` directory now contains nothing else.
2. **Http-Linear examples use a plugin name that does not exist.** The
example config used `Http-Linear { ... }`, but
`LinearSourceFactory#factoryIdentifier()` returns `Linear` (`getPluginName()`
returns `linear`). A job copied from the doc would fail plugin lookup at
runtime.
3. **Http-Linear option table was incomplete.** The doc listed only `url`,
`api_key`, and `plugin_output`, while its own example used `method` and `body`,
and the connector inherits the full HTTP source option set from
`HttpSourceFactory#getHttpBuilder()` and `HttpCommonOptions`.
4. **Http-Linear had no Chinese documentation and no changelog files**,
unlike every other connector (all `docs/{en,zh}/connectors/*` pages import a
changelog file).
5. **FakeSource documented options that do not exist, and missed options
that do.** The `Options table-names Case` example used `table-names = [...]`,
which is not a FakeSource option (not in `FakeSourceOptions`, not in
`FakeSourceFactory#optionRule()`; `table-names` only exists as a CDC catalog
option). Meanwhile the six date/time template options (`date.year.template`,
`date.month.template`, `date.day.template`, `time.hour.template`,
`time.minute.template`, `time.second.template`) defined in `FakeSourceOptions`
were missing from both the English and Chinese option tables.
6. **SNMP source missed its field-mapping options.** `oid_field`,
`value_field`, and `value_type_field` (defaults `oid` / `value` / `value_type`)
are defined in the SNMP connector options but were not documented, even though
the doc describes the fixed output column names.
7. **Sink common options diverged between English and Chinese.** The Chinese
page documented a `parallelism [int]` *sink* option, but `parallelism` is only
an `env`-level option (`EnvCommonOptions.PARALLELISM`); it is not part of
`SinkConnectorCommonOptions` and does not exist in the English page. The
English page was also missing the per-option description sections
(`plugin_input`, `metadata_datasource_id`) that the Chinese page has.
## What was changed
- Added `docs/en/connectors/source/Http-Linear.md` and
`docs/zh/connectors/source/Http-Linear.md`: complete pages (description, key
features, verified option table with defaults taken from `HttpSourceOptions` /
`HttpCommonOptions` / `LinearSourceOptions`, usage notes, corrected `Linear {
... }` examples) at the indexed path.
- Added `docs/en/connectors/changelog/connector-http-linear.md` (with the
#12270 entry) and the empty `docs/zh/...` changelog, matching the convention of
all other connectors (zh changelog files are empty placeholders).
- Deleted the orphan `docs/en/connector-v2/source/Http-Linear.md` (this
removes the now-empty `docs/en/connector-v2/` directory).
- `docs/{en,zh}/connectors/source/FakeSource.md`: added the six missing
date/time template option rows and removed the invalid `table-names` example
section.
- `docs/{en,zh}/connectors/source/SNMP.md`: added the three field-mapping
option rows.
- `docs/zh/connectors/common-options/sink-common-options.md`: removed the
phantom `parallelism` row and section.
- `docs/en/connectors/common-options/sink-common-options.md`: added the
`plugin_input` / `metadata_datasource_id` description sections to match the
Chinese page.
## Which areas/files were updated
- `docs/en/connectors/source/Http-Linear.md` (new),
`docs/zh/connectors/source/Http-Linear.md` (new)
- `docs/en/connectors/changelog/connector-http-linear.md` (new),
`docs/zh/connectors/changelog/connector-http-linear.md` (new)
- `docs/en/connector-v2/source/Http-Linear.md` (deleted)
- `docs/{en,zh}/connectors/source/FakeSource.md`
- `docs/{en,zh}/connectors/source/SNMP.md`
- `docs/{en,zh}/connectors/common-options/sink-common-options.md`
11 files changed, +303 / −79 lines.
## Language check
Yes — every fix was applied to both `docs/en` and `docs/zh` where the file
exists in both trees. The new Http-Linear page was written in both languages
from the start.
## Duplicate PR check (last 7 days)
I checked all PRs by this author and repo-wide docs PRs from the last 7 days
before starting:
- #12615 (Oct 3): file/CDC/Paimon/StarRocks/JDBC sink + dynamic-compile — no
overlap with this PR's files.
- #12609 (Oct 2): transforms + job configuration docs — no overlap.
- #12602 (Oct 1): formats + Clickhouse/Doris/Kafka etc. — no overlap.
- #12570 (Sep 30): Paimon/Redis/MongoDB-CDC/SqlServer-CDC — no overlap.
- #12553 (Sep 29, merged): en/zh option-table sync for JDBC family and file
sinks — no overlap.
None of these PRs touches the Http-Linear docs, FakeSource, SNMP, or the
sink common-options page, so this PR is not a duplicate.
## Verification
- Ran a repo-wide relative-link checker over `docs/en` and `docs/zh` before
and after the change: 0 dead links (the deleted orphan file was referenced by
no other page).
- Verified the new pages' `import ChangeLog ...` paths resolve to the added
changelog files in both languages.
- Verified option names, required flags, and default values against the
source: `LinearSourceFactory` / `LinearSourceOptions` /
`HttpSourceFactory#getHttpBuilder()` / `HttpSourceOptions` /
`HttpCommonOptions` for Http-Linear; `FakeSourceOptions` /
`FakeSourceFactory#optionRule()` for FakeSource; the SNMP connector options;
`SinkConnectorCommonOptions` / `EnvCommonOptions` for sink common options.
- Verified markdown table column counts are consistent (5-column option
tables) in all edited tables.
- Did not run the docusaurus build: the website build shell lives in the
separate apache/seatunnel-website repository, so it cannot run from this repo;
the checks above cover link integrity, imports, and table structure.
--
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]
