featzhang opened a new pull request, #27550:
URL: https://github.com/apache/flink/pull/27550
## What is the purpose of the change
Add an automatic detection and correction mechanism for Hugo ref syntax
errors in external connector documentation.
**Problem:** Some external connector repositories contain incorrect Hugo ref
shortcode syntax when referencing main Flink docs with anchors, causing build
failures.
**Solution:** Implement an automatic fix in the doc build process that
detects and corrects these syntax errors, ensuring documentation builds
successfully.
## Brief change log
- Add automatic syntax detection and correction in `docs/setup_docs.sh`
- Use sed to rewrite incorrect refs pointing to `docs/ops/*` and `docs/dev/*`
- Handle paths with trailing slashes before anchors
- Add documentation explaining the correct syntax
## Verifying this change
This change is already covered by existing CI checks:
- ✅ Verified locally by running `docs/setup_docs.sh` and `hugo --source docs`
- ✅ CI build passes after the fix
- ✅ Tested with various ref syntax patterns
## Does this pull request potentially affect one of the following parts:
- [ ] Dependencies (does it add or upgrade a dependency)
- [ ] The public API, i.e., is any changed class annotated with
`@Public(Evolving)`
- [x] The documentation (improves documentation build reliability)
- [ ] The serializers
- [ ] The runtime per-record code paths
- [ ] Anything that affects deployment or recovery: JobManager (and its
components), Checkpointing, Kubernetes/Yarn/Mesos, ZooKeeper
- [ ] The S3 file system connector
## Documentation
- Self-documenting with inline comments explaining the fix
- Resolves documentation build failures
- Provides guidance for connector maintainers
## Additional Context
**Incorrect syntax examples:**
```
{{< ref "docs/ops/production_ready/#anchor" >}}
{{< ref "docs/ops/metrics#kinesis-sink" >}}
```
**Correct syntax:**
```
{{< ref "docs/ops/production_ready" >}}#anchor
{{< ref "docs/ops/metrics" >}}#kinesis-sink
```
This automatic fix acts as a safety net, ensuring documentation builds
succeed even when connector repositories contain syntax errors. Connector
maintainers are encouraged to use the correct syntax in their repositories.
**Related Issues:**
- flink-connector-aws:
https://github.com/apache/flink-connector-aws/issues/XXX (to be created)
--
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]
