Iceberg - update schema page #354
Conversation
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThe changes remove the documentation page "choose-iceberg-mode.adoc" and its reference from the navigation, replacing it with a new page "specify-iceberg-schema.adoc". The new page covers supported Iceberg modes and schema integration, and includes content from an external source. The navigation structure is updated to reference the new documentation page under the "manage:iceberg" section. Sequence Diagram(s)Not applicable: The changes are limited to documentation structure and content updates without control flow or feature logic. Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Assessment against linked issues
Assessment against linked issues: Out-of-scope changesNo out-of-scope changes found. Possibly related PRs
Suggested reviewers
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
kbatuigas
force-pushed
the
DOC-1379-cloud-iceberg-json-schema
branch
from
5fe4ba8 to
4361d79
Compare
|
Since this is a rename, it's a good idea to add a redirect here https://github.com/redpanda-data/docs-site/blob/main/netlify.toml |
|
nvm, I see thhe page-alias now. LGTM |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
modules/ROOT/nav.adoc (1)
414-417: Consider adding explicit link text for the new pageThe previous entry hard-coded Choose Iceberg Mode as the label.
Relying on an empty xref ([]) falls back to the page title, which is fine, but if you want the navigation to match the old style or a shorter label (for example, “Specify Schema”), specify it explicitly:-*** xref:manage:iceberg/specify-iceberg-schema.adoc[] +*** xref:manage:iceberg/specify-iceberg-schema.adoc[Specify Iceberg Schema]Purely cosmetic, but helps keep the nav consistent.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
modules/ROOT/nav.adoc(1 hunks)modules/manage/pages/iceberg/choose-iceberg-mode.adoc(0 hunks)modules/manage/pages/iceberg/specify-iceberg-schema.adoc(1 hunks)
💤 Files with no reviewable changes (1)
- modules/manage/pages/iceberg/choose-iceberg-mode.adoc
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#267
File: modules/manage/pages/maintenance.adoc:63-64
Timestamp: 2025-04-25T01:42:09.318Z
Learning: The timeline for major upgrade notifications (180 days in advance) was intentionally removed from the Redpanda Cloud maintenance documentation, even though it was mentioned in the PR objectives.
📚 Learning: in asciidoc documentation used by redpanda, empty cross-references (xrefs) without link text (like `...
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#278
File: modules/manage/pages/cluster-maintenance/config-cluster.adoc:75-75
Timestamp: 2025-04-29T18:43:42.666Z
Learning: In AsciiDoc documentation used by Redpanda, empty cross-references (xrefs) without link text (like `xref:manage:rpk/intro-to-rpk.adoc[]`) automatically use the target page's title as the link text.
Applied to files:
modules/ROOT/nav.adoc
📚 Learning: in the redpanda cloud documentation system using asciidoctor, glossary cross-references with spaces ...
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#350
File: modules/get-started/pages/cloud-overview.adoc:55-56
Timestamp: 2025-07-16T21:11:59.964Z
Learning: In the Redpanda Cloud documentation system using Asciidoctor, glossary cross-references with spaces in the ID (like `glossterm:data plane[]`) work correctly and do not need to be changed to hyphenated forms. The existing syntax is functional and should not be modified.
Applied to files:
modules/ROOT/nav.adoc
| :description: Learn about supported Iceberg modes and how you can integrate schemas with Iceberg topics. | ||
| :page-aliases: manage:iceberg/choose-iceberg-mode.adoc | ||
|
|
||
| include::ROOT:manage:iceberg/specify-iceberg-schema.adoc[tag=single-source] No newline at end of file |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Include path is likely invalid or self-referential
The directive
include::ROOT:manage:iceberg/specify-iceberg-schema.adoc[tag=single-source]
uses two : separators instead of the required : (family) + $ (path) pattern.
As written, Antora may treat manage as a family name (which is unsupported) and the build will raise an “unresolved include” or, worse, recurse on the same file.
Proposed fix (assumes the single-source file lives in modules/ROOT/pages/manage/iceberg/):
-include::ROOT:manage:iceberg/specify-iceberg-schema.adoc[tag=single-source]
+// Single-source content lives in the ROOT module under pages/
+include::ROOT:pages$manage/iceberg/specify-iceberg-schema.adoc[tag=single-source]Please verify the actual location and adjust family/path accordingly.
I want to confirm the actual file layout and include usage before updating the comment. Let's locate the target AsciiDoc file and inspect its include directives:
🏁 Script executed:
#!/usr/bin/env bash
# Find every occurrence of specify-iceberg-schema.adoc in the repo
fd specify-iceberg-schema.adoc
# Show the include::ROOT directive in the file under review
rg "include::ROOT" -n modules/manage/pages/iceberg/specify-iceberg-schema.adoc || trueLength of output: 246
Let’s confirm how the Antora playbook defines the ROOT module and its page roots:
🏁 Script executed:
#!/usr/bin/env bash
# Locate the Antora playbook
fd antora-playbook.*yml
# If it exists, show its modules section
if [ -f antora-playbook.yml ]; then
grep -R "modules:" -n antora-playbook.yml | sed -n '1,10p'
sed -n '1,200p' antora-playbook.yml | sed -n '/modules:/,$p'
fiLength of output: 86
I need to confirm how the ROOT module is declared in your Antora playbook before suggesting the exact include syntax. Let’s inspect the top of local-antora-playbook.yml to see the modules: definitions:
🏁 Script executed:
#!/usr/bin/env bash
# Show the first 200 lines of the playbook to inspect module declarations
sed -n '1,200p' local-antora-playbook.ymlLength of output: 2937
I want to verify that the single-source file actually lives under the ROOT module before suggesting the updated include syntax. Let’s check for it:
🏁 Script executed:
#!/usr/bin/env bash
# Confirm the ROOT module exists and locate the shared AsciiDoc file
if [ -d modules/ROOT ]; then
echo "Found modules/ROOT—searching for specify-iceberg-schema.adoc under ROOT/pages..."
fd specify-iceberg-schema.adoc modules/ROOT/pages
else
echo "modules/ROOT directory not found"
fiLength of output: 354
Let’s inspect the modules directory and drill into modules/ROOT to see its layout:
🏁 Script executed:
#!/usr/bin/env bash
# List all modules
echo "Modules:"
ls -1 modules
# If ROOT exists, show its full tree
if [ -d modules/ROOT ]; then
echo -e "\nmodules/ROOT structure:"
ls -R modules/ROOT
else
echo "modules/ROOT not found"
fiLength of output: 520
Invalid include path: no modules/ROOT/pages or duplicate file
On line 5 of modules/manage/pages/iceberg/specify-iceberg-schema.adoc, the directive
include::ROOT:manage:iceberg/specify-iceberg-schema.adoc[tag=single-source]points at modules/ROOT/pages/manage/iceberg/specify-iceberg-schema.adoc, but the ROOT module has no pages folder and no copy of this file.
Possible fixes:
- If there is a separate “single-source” AsciiDoc file, move it into the correct module’s
pages/icebergdirectory (for example, undermodules/shared/pages/iceberg) and update the include to use Antora’sfamily:pages$pathsyntax:(Replace-include::ROOT:manage:iceberg/specify-iceberg-schema.adoc[tag=single-source] +include::shared:pages$iceberg/specify-iceberg-schema.adoc[tag=single-source]
sharedwith the actual module name where the file lives.) - If no external file exists (i.e. you’re including the same document), remove the include or replace it with a valid relative include.
Please confirm where the single-source file actually resides and correct the include directive accordingly.
🤖 Prompt for AI Agents
In modules/manage/pages/iceberg/specify-iceberg-schema.adoc at line 5, the
include directive uses an invalid path referencing
ROOT:manage:iceberg/specify-iceberg-schema.adoc, but the ROOT module lacks a
pages folder and this file. To fix, verify the actual location of the
single-source AsciiDoc file; if it exists in another module like shared, move it
to that module's pages/iceberg directory and update the include to use the
correct Antora family:pages$path syntax. If no separate file exists, remove the
include or replace it with a valid relative include path within the current
module.
Description
Related: redpanda-data/docs#1207
This pull request makes updates to the Antora playbook and navigation structure to reflect changes in Iceberg schema documentation. It replaces the "Choose Iceberg Mode" page with a new "Specify Iceberg Schema" page and updates references accordingly.
Documentation Updates for Iceberg Schema:
local-antora-playbook.yml: Updated the branch list for thedocumentationrepository to include theDOC-1379-document-feature-iceberg-support-for-json-schemabranch.modules/ROOT/nav.adoc: Replaced the navigation reference for "Choose Iceberg Mode" with a new reference for "Specify Iceberg Schema."modules/manage/pages/iceberg/choose-iceberg-mode.adoc: Removed the "Choose Iceberg Mode" page, including its description and beta tag.modules/manage/pages/iceberg/specify-iceberg-schema.adoc: Added a new page titled "Specify Iceberg Schema," including its description, beta tag, and an alias pointing to the removed "Choose Iceberg Mode" page for backward compatibility.Resolves https://github.com/redpanda-data/documentation-private/issues/
Review deadline: 21 July
Page previews
Specify Iceberg Schema
Checks