Repository navigation
Source the Connect reference partials from the Connect release asset - #5
Conversation
5.52.0 has the modify-connect-tag-playbook version that keeps only the generated partials and examples from the connect source.
docs-extensions-and-macros removed it in 5.30.0. Antora's own redirect producer runs on every build without an extension.
…ease asset Connect no longer commits its generated docs, so its next release has no docs/antora.yml and Antora would fail to aggregate the source. The modify-connect-tag-playbook extension adds the partials from the release asset instead, once docs-extensions-and-macros ships that mode.
|
Heads-up: please hold this PR until redpanda-data/docs-extensions-and-macros#358 is released. redpanda-data/connect#4863 merged today, so upcoming Connect releases will no longer include So once #358 is released, this PR can drop the connect content-source lines, keep only the |
Technical check: Connect release-asset cutoverOverall: Ready to merge. This repo has no CI checks or deploy preview, so I built it locally at Hold conditions: all metThese are the same as on the sibling PRs (redpanda-data/docs#2117, redpanda-data/cloud-docs#748, redpanda-data/adp-docs#356, redpanda-data/redpanda-labs#309): redpanda-data/connect#4876 merged, Connect v4.113.0 ships the asset, redpanda-data/docs-extensions-and-macros#358 is in v5.54.0, the content-source lines were dropped ( Local build at
|
| Check | Result |
|---|---|
npm ci |
2,369 packages, exit 0 |
antora --fetch |
Exit 0, 9,150 HTML pages |
| Log | 1 error, 43 warnings. None of them comes from this PR (details below). |
| Connect output | connect/components/outputs/kafka_franz/ renders with 108 unique IDs |
Where the log messages come from:
- The one error:
xref:home:ROOT:how-to-use-these-docs.adocin cloud-docs'cloud-mcp/overview.adoc. The home component lives in docs-site, which this playbook doesn't aggregate. - 39 warnings:
tag 'deprecated'or'exclude-from-docs' not found in include file, from aggregated content. - The rest: two
Cloud docs missing for: websocketnotices from the 4.113.0 connector data, one missing-attribute warning, and a stalesite.start_page(suggestion 2).
Suggestions
-
The PR body is out of date. The same bullet as on the siblings asks for the bump, and the body should also say why
modify-redirectswas removed. Consider: "Bumped to 5.54.0 (includes #358), up from a lockfile pinned at 3.7.0. Dropsmodify-redirects, which docs-extensions-and-macros no longer ships." -
Not caused by this PR: the template's start page is stale. The build warns
Start page specified for site not found: ROOT:get-started:intro-to-events.adoc. New repos copy this playbook, so it's worth fixing in a follow-up. -
Not caused by this PR: the same Bloblang JSON 404 as the siblings. The local build sets
connect-json-urltohttps://docs.redpanda.com/connect/components/_attachments/connect-4.113.0.json, but onlyconnect-4.112.0.jsonis published. Registeringset-available-attachment-versionsfixes it.
Impact on other repos
- redpanda-data/rp-connect-docs#531: the same note as on the sibling PRs. The release asset doesn't include
connect-<version>.json, so that file still depends on rp-connect-docs' auto-docs regen after the cutover.
What works well
- The two-major-version jump is safe. All 17 extension and macro paths in the playbook exist in 5.54.0, and Antora (3.1.2) and Asciidoctor (2.2.6) are unchanged. The only other version changes are two Octokit patch bumps.
- Pinning
^5.54.0instead of"latest"makespackage.jsonmatch what the lockfile actually installs. - Correct extension order:
modify-connect-tag-playbookis now first, beforegenerate-rp-connect-info.
… at a file that exists
|
Thanks @Feediver1. Updated the description, and f966876 registers |
micheleRP
left a comment
There was a problem hiding this comment.
LGTM. Lockfile resolves docs-extensions-and-macros 5.54.0, and the playbook only affects PR previews.
Registers the
modify-connect-tag-playbookextension so the Connect reference partials (fields, examples, metadata, descriptions, and the Bloblang reference) come from the latest Connect release instead of rp-connect-docs.Connect no longer commits its generated docs. Each Connect release attaches them as
redpanda-connect-docs.tar.gz, and the extension downloads that asset and adds the files to theconnectcomponent. This playbook doesn't list the connect repo as a content source.Notes:
modify-redirects, which docs-extensions-and-macros no longer ships, so requiring it fails the build.set-available-attachment-versions, as docs-site does, so the Bloblang playground'sconnect-json-urlpoints at the newestconnect-<version>.jsonthat exists instead of one auto-docs hasn't generated yet.