Feature: Reorganize usage guide about logical replication (CCR)

[amotl]

About

Just a little refactoring, nothing wild.

[coderabbitai]

Walkthrough

Documentation refactoring that reorganizes logical replication and Cross-Cluster Replication (CCR) content. Removes a "Logical Replication" toctree entry from the clustering index, updates CCR index links and descriptions, and introduces reference anchors to consolidate documentation structure.

Changes

Cohort / File(s)	Change Summary
Navigation restructuring docs/admin/clustering/index.md	Removed "Logical Replication" entry from toctree, eliminating the cross-tree navigation link
CCR index updates docs/feature/ccr/index.md	Updated internal link from "logical-replication-setup" to "ccr-usage"; refined descriptive text from "Hands-on tutorial" to "Hands-on usage guide"; updated workstation description to clarify "two CrateDB instances"; added Usage toctree block with hidden entry
Reference anchors docs/feature/ccr/usage.md	Added two top-level section anchors at document start: (ccr-usage)= and (logical-replication-setup)= to support new navigation targets

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

All changes are straightforward documentation updates—toctree entry removal, link redirection, and anchor additions. No complex logic or multi-file dependencies to reason through.

Possibly related PRs

• Navigation: Dissolve cross-tree references #362: Updates documentation navigation and toctree links similar to this PR's restructuring of cross-tree references.
• Wording: Tame use of "This section..." #384: Edits the logical-replication-setup page content while this PR modifies navigation to the same documentation.

Suggested labels

refactoring

Suggested reviewers

• kneth
• surister
• hammerhead

Poem

🐰 The links are rearranged with care,
Navigation anchors placed just there,
Logical paths now clustered tight,
CCR usage shining bright! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Feature: Reorganize usage guide about logical replication (CCR)" directly and accurately reflects the main changes in the pull request. The raw summary shows that the PR reorganizes documentation by removing a toctree entry, updating internal links and descriptions, and adding section anchors for the logical replication/CCR documentation. The title is clear, concise, and specific enough that a teammate scanning the history would understand the primary change is a reorganization of the CCR usage guide documentation.
Description Check	✅ Passed	The pull request description states "Just a little refactoring, nothing wild," which is related to the changeset since the PR is indeed about refactoring and reorganizing the documentation structure around logical replication and CCR. While the description is minimal and vague, it is not completely off-topic or unrelated to the changes. Given that the check is designed to be lenient and should pass as long as the description is not completely off-topic, this description meets the threshold for passing.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature-ccr-usage

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d9ad151 and ebb3ae6.

📒 Files selected for processing (3)

• docs/admin/clustering/index.md (0 hunks)
• docs/feature/ccr/index.md (1 hunks)
• docs/feature/ccr/usage.md (1 hunks)

💤 Files with no reviewable changes (1)

• docs/admin/clustering/index.md

🧰 Additional context used

🧠 Learnings (9)

📓 Common learnings

Learnt from: bmunkholm
Repo: crate/cratedb-guide PR: 340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 235
File: docs/start/index.md:1-3
Timestamp: 2025-08-23T15:09:38.537Z
Learning: In the CrateDB Guide documentation, the `(use)=` label in `docs/start/index.md` is intentionally placed alongside `(getting-started)=` as part of the documentation architecture, even though it may appear to conflict with top-level "Use" section labeling. This is a deliberate design decision by the maintainers.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 0
File: :0-0
Timestamp: 2025-10-06T13:45:25.891Z
Learning: For the cratedb-guide repository, general discussions and broader documentation concerns should be added to the existing runsheet/tracking ticket (e.g., GH-227) rather than creating separate issues.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 0
File: :0-0
Timestamp: 2025-10-06T16:40:16.322Z
Learning: In the crate/cratedb-guide repository, documentation is organized by content type: files in `docs/feature/`, `docs/integrate/`, and `docs/ingest/` are reference material designed for quick access, while `docs/start/` contains learning path content. Reference material sections use top-right reference layouts for efficient navigation.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 420
File: docs/connect/erlang.md:100-113
Timestamp: 2025-10-19T19:21:49.864Z
Learning: In the cratedb-guide repository, when documenting cloud or alternative connection methods, show only the differences from the canonical example (e.g., SSL configuration) rather than repeating the entire workflow (query execution, cleanup, etc.). This pattern is used consistently across pages to avoid repetition.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 236
File: docs/index.md:312-316
Timestamp: 2025-08-09T11:00:03.578Z
Learning: In the CrateDB Guide documentation, locally stale references (such as `(reference-architectures)=`, `(domain)=`, and similar anchor labels) should be retained even when they appear unused within the repository, as external projects might still reference them. This ensures backward compatibility for external documentation and projects.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.

Learnt from: amotl
Repo: crate/cratedb-guide PR: 204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.

📚 Learning: 2025-08-09T11:00:03.578Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 236
File: docs/index.md:312-316
Timestamp: 2025-08-09T11:00:03.578Z
Learning: In the CrateDB Guide documentation, locally stale references (such as `(reference-architectures)=`, `(domain)=`, and similar anchor labels) should be retained even when they appear unused within the repository, as external projects might still reference them. This ensures backward compatibility for external documentation and projects.

Applied to files:

• docs/feature/ccr/usage.md
• docs/feature/ccr/index.md

📚 Learning: 2025-08-23T15:09:38.537Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 235
File: docs/start/index.md:1-3
Timestamp: 2025-08-23T15:09:38.537Z
Learning: In the CrateDB Guide documentation, the `(use)=` label in `docs/start/index.md` is intentionally placed alongside `(getting-started)=` as part of the documentation architecture, even though it may appear to conflict with top-level "Use" section labeling. This is a deliberate design decision by the maintainers.

Applied to files:

• docs/feature/ccr/usage.md
• docs/feature/ccr/index.md

📚 Learning: 2025-08-14T11:40:39.584Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 249
File: docs/ingest/etl/index.md:30-31
Timestamp: 2025-08-14T11:40:39.584Z
Learning: In the CrateDB Guide documentation, the project policy is to prune ALL legacy aliases (like `(apache-airflow)=`, `(aws-*)=`) and fix forward if anything breaks, rather than maintaining backward compatibility with dual anchors.

Applied to files:

• docs/feature/ccr/usage.md

📚 Learning: 2025-09-25T19:31:54.320Z

Learnt from: bmunkholm
Repo: crate/cratedb-guide PR: 340
File: docs/home/index.md:84-97
Timestamp: 2025-09-25T19:31:54.320Z
Learning: In the CrateDB Guide docs (MyST), the CrateDB Cloud card on the homepage should link to `getting-started` using `:link-type: ref` instead of the previous `cloud:index` intersphinx target. This change was implemented in PR #340 to direct users to the getting started section rather than directly to the Cloud documentation.

Applied to files:

• docs/feature/ccr/index.md

📚 Learning: 2025-10-19T19:21:49.864Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 420
File: docs/connect/erlang.md:100-113
Timestamp: 2025-10-19T19:21:49.864Z
Learning: In the cratedb-guide repository, when documenting cloud or alternative connection methods, show only the differences from the canonical example (e.g., SSL configuration) rather than repeating the entire workflow (query execution, cleanup, etc.). This pattern is used consistently across pages to avoid repetition.

Applied to files:

• docs/feature/ccr/index.md

📚 Learning: 2025-10-06T16:40:16.322Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 0
File: :0-0
Timestamp: 2025-10-06T16:40:16.322Z
Learning: In the crate/cratedb-guide repository, documentation is organized by content type: files in `docs/feature/`, `docs/integrate/`, and `docs/ingest/` are reference material designed for quick access, while `docs/start/` contains learning path content. Reference material sections use top-right reference layouts for efficient navigation.

Applied to files:

• docs/feature/ccr/index.md

📚 Learning: 2025-05-18T13:25:11.786Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.

Applied to files:

• docs/feature/ccr/index.md

📚 Learning: 2025-05-18T12:50:36.393Z

Learnt from: amotl
Repo: crate/cratedb-guide PR: 204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.

Applied to files:

• docs/feature/ccr/index.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build docs

🔇 Additional comments (5)

docs/feature/ccr/index.md (4)

89-92: Toctree addition establishes navigation structure for Usage content.

The hidden toctree entry consolidates the Usage page within the CCR index hierarchy, supporting the reorganized documentation structure. This aligns with the usage.md anchor additions and clarifies the information architecture.

---

101-102: Link target correctly updated to new ccr-usage anchor.

The Learn card link now points to ccr-usage with :link-type: ref, which correctly targets the new anchor added in docs/feature/ccr/usage.md. This ensures the link resolves to the intended page under the modernized terminology.

---

109-110: Text refinements improve clarity and precision.

The updates from "Hands-on tutorial" to "Hands-on usage guide" and explicit "two CrateDB instances" better reflect the content purpose and reduce ambiguity. These are minor but valuable clarity improvements.

---

87-130: No issues found. Cross-references are correctly configured and no broken links to removed clustering entry remain.

Verification confirms:

• ccr-usage link target resolves to (ccr-usage)= anchor in docs/feature/ccr/usage.md
• cloud:logical-replication follows established intersphinx pattern (confirmed in _include/links.md)
• No remaining references to logical replication in docs/admin/clustering/
• Migration from clustering index to CCR index complete

docs/feature/ccr/usage.md (1)

1-2: Dual-anchor implementation correctly executed; refactoring is sound.

The verification confirms this is well-implemented backward-compatible refactoring:

• The new (ccr-usage)= anchor is actively referenced internally (docs/feature/ccr/index.md:101 uses :link: ccr-usage)
• The legacy (logical-replication-setup)= anchor has zero internal references, preserved only for external projects that may still link to it
• No internal navigation conflicts detected

This aligns with established documentation policy (PR 236 learning) of retaining legacy anchors for external stability while updating internal references to new naming conventions.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}