Layout: Curated index page for "Administration" and "Performance Guides" #265
Conversation
|
Warning Rate limit exceeded@amotl has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 8 minutes and 22 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (11)
WalkthroughAdds new Markdown index pages for Administration and Performance, removes the legacy reStructuredText index files, and applies minor title/content edits in several performance docs (inserts/selects/storage). All changes are documentation-only. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
amotl
added
sanding-1200
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (7)
docs/performance/index.md (4)
22-24: Tighten phrasing for clarity and style.Minor editorial tweaks improve readability and tone.
-About under- and over-allocation of shards vs. finding the right balance, -optimizing for ingestion performance, memory capacity planning, and -about limits and recommendations related to storage details. +Guidance on balancing shard allocation, optimizing ingestion performance, +planning memory capacity, and limits/recommendations related to storage.
36-40: Adopt neutral tone and fix wording ("less" → "lower").Prefer concise, neutral language in docs.
-Optimally design your SQL query statements for maximum performance and -less resource consumption. -When milliseconds matter, or otherwise a query using too many resources -would set your cluster on fire. +Design SQL statements for maximum performance and lower resource usage. +Applicable when latency matters, or when a resource‑heavy query could overload your cluster.
17-20: Optional: Title-case link captions for consistency.Only "Sharding" is title-cased. Consider aligning others.
-Sharding <sharding> -scaling -storage +Sharding <sharding> +Scaling <scaling> +Storage <storage>
1-1: Preserve legacy anchors for inbound links (if they existed).If older pages referenced a label like
performance-guides, add an alias to avoid broken cross-refs.-(performance)= +(performance)= +(performance-guides)=If unsure, run a quick check for references to
performance-guidesacross the repo and add the alias only if matches are found.docs/admin/index.md (3)
9-13: Breakpoint choice: consider 1 2 3 3 for smoother scaling.Optional UX tweak:
1 2 3 3yields two columns on medium screens instead of jumping straight to three, which can read better.-:::::{grid} 1 3 3 3 +:::::{grid} 1 2 3 3
35-35: Docname style: prefer absolute docnames for long-term maintainability.Using
../performance/indexworks, but many teams standardize on absolute docnames from the docs root (e.g.,performance/index). Consider aligning with the prevalent style in this repo.-../performance/index +performance/indexBefore changing, grep the repo to see which style dominates and follow that.
5-7: Intro text is clear; consider minor polish.Very small tweak to avoid repetition.
-CrateDB database cluster administration best practices. +Best practices for administering CrateDB clusters.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
docs/admin/index.md(1 hunks)docs/admin/index.rst(0 hunks)docs/performance/index.md(1 hunks)docs/performance/index.rst(0 hunks)
💤 Files with no reviewable changes (2)
- docs/performance/index.rst
- docs/admin/index.rst
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#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.
🪛 LanguageTool
docs/performance/index.md
[grammar] ~1-~1: There might be a mistake here.
Context: (performance)= # Performance Guides :::{div} sd-text-mut...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...ormance tuning. ::: :::::{grid} 1 2 2 2 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ...
(QB_NEW_EN)
[grammar] ~9-~9: There might be a mistake here.
Context: ...:: :::::{grid} 1 2 2 2 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ::::{grid-item-c...
(QB_NEW_EN)
[grammar] ~10-~10: There might be a mistake here.
Context: ...id} 1 2 2 2 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ::::{grid-item-card} {materi...
(QB_NEW_EN)
docs/admin/index.md
[grammar] ~1-~1: There might be a mistake here.
Context: (admin)= (administration)= # Administration :::{...
(QB_NEW_EN)
[grammar] ~2-~2: There might be a mistake here.
Context: (admin)= (administration)= # Administration :::{div} sd-text-muted C...
(QB_NEW_EN)
[grammar] ~9-~9: There might be a mistake here.
Context: ...best practices. ::: :::::{grid} 1 3 3 3 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ...
(QB_NEW_EN)
[grammar] ~10-~10: There might be a mistake here.
Context: ...:: :::::{grid} 1 3 3 3 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ::::{grid-item-c...
(QB_NEW_EN)
[grammar] ~11-~11: There might be a mistake here.
Context: ...id} 1 3 3 3 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ::::{grid-item-card} {materi...
(QB_NEW_EN)
[grammar] ~25-~25: There might be a mistake here.
Context: ...it-breaker troubleshooting/index ``` +++ Production and troubleshooting guideline...
(QB_NEW_EN)
[grammar] ~26-~26: There might be a mistake here.
Context: ...nes, and system resource considerations. :::: ::::{grid-item-card} {material-out...
(QB_NEW_EN)
🔇 Additional comments (4)
docs/performance/index.md (2)
8-12: Grid layout looks correct and responsive-friendly.Use of nested MyST fences with 5/4 colons, breakpoints
1 2 2 2, and spacing options is valid for sphinx-design.
17-20: All performance toctree targets verified – no missing files found.I ran the provided script against
docs/performanceand confirmed that the following docnames resolve as.mdfiles:
- docs/performance/sharding.md
- docs/performance/scaling.md
- docs/performance/storage.md
- docs/performance/inserts/index.md
- docs/performance/selects.md
- docs/performance/optimization.md
No build warnings should occur due to missing toctree entries.
docs/admin/index.md (2)
1-3: Dual labels are a nice touch for back-compat.Adding both
(admin)and(administration)should help preserve existing cross-references.
15-24: Confirm TOC docnames and:maxdepth:in docs/admin/index.md
All referenced docnames have been verified to exist in the
docs/tree:
• bootstrap-checks
• create-user
• going-into-production
• memory
• circuit-breaker
• troubleshooting/index
• clustering/index
• sharding-partitioning
• performance/index
• upgrade/indexThe main TOC blocks use
:maxdepth: 1, whereas the Upgrades section is set to:maxdepth: 2.
• If this deeper level is intentional for the Upgrades content, no change is needed.
• Otherwise, consider aligning all TOC blocks to the same:maxdepth:for consistency.Please review the TOC blocks in docs/admin/index.md at lines 15–24, 30–36, and 43–47 to confirm the intended depth settings.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
docs/performance/index.md (2)
14-25: Card content structure is good; optional enhancement: make the whole card clickable.Embedding a
{toctree}inside the card body works well. If you want the entire card to act as a link (not just the list items), consider adding a:link:to a canonical landing page for this theme (e.g.,shardingorstorage) so users can click anywhere on the card.Example diff (pick a target page you prefer):
-::::{grid-item-card} {material-outlined}`tune;2em` Allocation and Capacity +::::{grid-item-card} {material-outlined}`tune;2em` Allocation and Capacity +:link: sharding
27-39: Minor copy polish (optional).The message is clear; consider slightly tightening phrasing.
-Design SQL statements for maximum performance and lower resource usage. -Applicable when latency matters, or when a resource‑heavy query could -overload your cluster. +Design SQL statements for maximum performance and reduced resource usage. +Use when latency matters or when a resource‑heavy query could overload +your cluster.docs/admin/index.md (3)
14-27: Copy edit nit (optional) and consider card link.
- Style: remove the comma before “and” for a tighter sentence.
- Optional: add
:link:so the whole card is clickable (e.g., togoing-into-production).-Production and troubleshooting guidelines, and system resource considerations. +Production and troubleshooting guidelines and system resource considerations.-::::{grid-item-card} {material-outlined}`lightbulb;2em` General +::::{grid-item-card} {material-outlined}`lightbulb;2em` General +:link: going-into-production
29-41: Cluster card: optional phrasing tweak.Minor tightening for flow.
-Best practices and tips around the topics of -clustering, sharding, partitioning, and performance tuning. +Best practices and tips for clustering, sharding, partitioning, and performance tuning.Also consider a
:link:toclustering/indexso the card is clickable.-::::{grid-item-card} {material-outlined}`speed;2em` Cluster +::::{grid-item-card} {material-outlined}`speed;2em` Cluster +:link: clustering/index
42-51: Upgrades card: consistent tone (optional) and clickable card.Two small edits for brevity; optional
:link:toupgrade/index.-Guidelines about upgrading CrateDB clusters in production, -from planning to execution. +Guidelines for upgrading CrateDB clusters in production—from planning to execution.-::::{grid-item-card} {material-outlined}`system_update_alt;2em` Software Upgrades +::::{grid-item-card} {material-outlined}`system_update_alt;2em` Software Upgrades +:link: upgrade/index
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (5)
docs/admin/index.md(1 hunks)docs/performance/index.md(1 hunks)docs/performance/inserts/index.rst(1 hunks)docs/performance/selects.rst(1 hunks)docs/performance/storage.md(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- docs/performance/storage.md
- docs/performance/selects.rst
- docs/performance/inserts/index.rst
🧰 Additional context used
🧠 Learnings (8)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#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.
📚 Learning: 2025-08-23T22:52:44.211Z
Learnt from: amotl
PR: crate/cratedb-guide#265
File: docs/performance/index.md:21-21
Timestamp: 2025-08-23T22:52:44.211Z
Learning: The `+++` syntax is supported in MyST Markdown as a block separator inside `{grid-item-card}` directives, used to create thematic breaks or separate sections within card content.
Applied to files:
docs/admin/index.mddocs/performance/index.md
📚 Learning: 2025-05-18T13:25:11.786Z
Learnt from: amotl
PR: crate/cratedb-guide#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/admin/index.mddocs/performance/index.md
📚 Learning: 2025-08-23T22:52:46.510Z
Learnt from: amotl
PR: crate/cratedb-guide#265
File: docs/admin/index.md:25-27
Timestamp: 2025-08-23T22:52:46.510Z
Learning: The `+++` separator is supported and valid in MyST Markdown/Sphinx, including within `{grid-item-card}` elements, and does not cause bleeding into rendered output.
Applied to files:
docs/admin/index.mddocs/performance/index.md
📚 Learning: 2025-06-06T08:46:08.709Z
Learnt from: amotl
PR: crate/cratedb-guide#0
File: :0-0
Timestamp: 2025-06-06T08:46:08.709Z
Learning: The `{rubric}` syntax (with single curly braces) is correct and valid in MyST Markdown, as employed by MyST.
Applied to files:
docs/admin/index.mddocs/performance/index.md
📚 Learning: 2025-06-06T08:46:34.552Z
Learnt from: amotl
PR: crate/cratedb-guide#0
File: :0-0
Timestamp: 2025-06-06T08:46:34.552Z
Learning: In MyST Markdown, the `{rubric}` syntax is correct as employed by MyST for rubric directives.
Applied to files:
docs/admin/index.mddocs/performance/index.md
📚 Learning: 2025-05-18T13:39:58.391Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/cratedb-mcp.md:3-8
Timestamp: 2025-05-18T13:39:58.391Z
Learning: In MyST Markdown, the correct syntax for rubric directives in the CrateDB documentation is:
```
:::{rubric} Title
:::
```
followed by the content outside of the directive. This is different from other admonition blocks where content is typically wrapped inside the directive.
Applied to files:
docs/admin/index.mddocs/performance/index.md
📚 Learning: 2025-06-06T08:46:34.552Z
Learnt from: amotl
PR: crate/cratedb-guide#0
File: :0-0
Timestamp: 2025-06-06T08:46:34.552Z
Learning: Rubric directives (`{rubric}` and `:::{rubric}`) are correct and valid MyST Markdown syntax for creating informal headings.
Applied to files:
docs/performance/index.md
🪛 LanguageTool
docs/admin/index.md
[grammar] ~1-~1: There might be a mistake here.
Context: (admin)= (administration)= # Administration :::{...
(QB_NEW_EN)
[grammar] ~2-~2: There might be a mistake here.
Context: (admin)= (administration)= # Administration :::{div} sd-text-muted B...
(QB_NEW_EN)
[grammar] ~9-~9: There might be a mistake here.
Context: ...abase clusters. ::: :::::{grid} 1 2 3 3 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ...
(QB_NEW_EN)
[grammar] ~10-~10: There might be a mistake here.
Context: ...:: :::::{grid} 1 2 3 3 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ::::{grid-item-c...
(QB_NEW_EN)
[grammar] ~11-~11: There might be a mistake here.
Context: ...id} 1 2 3 3 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ::::{grid-item-card} {materi...
(QB_NEW_EN)
[grammar] ~25-~25: There might be a mistake here.
Context: ...it-breaker troubleshooting/index ``` +++ Production and troubleshooting guideline...
(QB_NEW_EN)
[grammar] ~26-~26: There might be a mistake here.
Context: ...nes, and system resource considerations. :::: ::::{grid-item-card} {material-out...
(QB_NEW_EN)
docs/performance/index.md
[grammar] ~1-~1: There might be a mistake here.
Context: (performance)= (performance-guides)= # Performance Guid...
(QB_NEW_EN)
[grammar] ~2-~2: There might be a mistake here.
Context: (performance)= (performance-guides)= # Performance Guides :::{div} sd-text-mut...
(QB_NEW_EN)
[grammar] ~9-~9: There might be a mistake here.
Context: ...ormance tuning. ::: :::::{grid} 1 2 2 2 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ...
(QB_NEW_EN)
[grammar] ~10-~10: There might be a mistake here.
Context: ...:: :::::{grid} 1 2 2 2 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ::::{grid-item-c...
(QB_NEW_EN)
[grammar] ~11-~11: There might be a mistake here.
Context: ...id} 1 2 2 2 :margin: 4 4 0 0 :padding: 0 :gutter: 2 ::::{grid-item-card} {materi...
(QB_NEW_EN)
[grammar] ~37-~37: There might be a mistake here.
Context: ...rs, or when a resource‑heavy query could overload your cluster. :::: :::::
(QB_NEW_EN)
[grammar] ~38-~38: There might be a mistake here.
Context: ...heavy query could overload your cluster. :::: :::::
(QB_NEW_EN)
⏰ 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 (8)
docs/performance/index.md (4)
1-7: Anchors and intro look correct; preserves backlinks.Dual labels
(performance)and(performance-guides)before the H1 are valid MyST targets and help keep old inbound links working. The muted lead-in block is fine.
9-13: Responsive grid configuration is solid.
{grid} 1 2 2 2gives a single column on narrow screens and two on larger; margins/padding/gutter settings are consistent with sphinx-design usage.
22-22: Keep the+++separator; it’s valid here.Confirmed:
+++is supported by MyST inside{grid-item-card}as a block separator; no change needed.
15-21: All toctree targets in docs/performance/index.md have been verifiedI ran the provided script and confirmed that the following files exist under docs/performance, so the toctree entries for
sharding,scaling,storage,inserts/index,selects, andoptimizationwill resolve correctly. No broken links are expected, and no further changes are required.docs/admin/index.md (4)
1-7: Good use of dual anchors and concise intro.
(admin)and(administration)labels should preserve legacy links; the muted lead-in sets context nicely.
9-13: Grid layout is appropriate for an index hub.
{grid} 1 2 3 3scales well across breakpoints; spacing options look consistent with the Performance page.
25-25:+++separators are correct here.As discussed earlier and captured in learnings,
+++works inside{grid-item-card}; keep as-is.Also applies to: 37-37, 48-48
15-24: All Toctree targets verified—please confirm maxdepth settings
- All referenced files under docs/admin/index.md (including bootstrap-checks, create-user, going-into-production, memory, circuit-breaker, troubleshooting/index, clustering/index, sharding-partitioning, ../performance/index, upgrade/index) exist.
- Please confirm that using
:maxdepth: 1for the General and Cluster sections and:maxdepth: 2for the Upgrades section is intentional for your navigation hierarchy.- This check applies to the toctree blocks at lines 15–24, 30–36, and 44–47.
All content has been absorbed by `cratedb-guide` already.
Automatic toctree directives are maintenance-free, but the pure variants don't provide much guidance to users. Combining them with design elements and responsive grid layouts significantly improves flexibility for guiding readers. Also, migrate from reStructuredText to Markdown.
amotl
force-pushed
the
admin-performance-curated-index
branch
from
68f7c29 to
e38eaef
Compare
About
A proposal to remove walls of links but use cards instead for better guidance into relevant topics.
Preview
https://cratedb-guide--265.org.readthedocs.build/admin/
https://cratedb-guide--265.org.readthedocs.build/performance/
Details
Automatic toctree directives are maintenance-free, but the pure variants don't provide much guidance to users. Combining them with design elements and responsive grid layouts significantly improves flexibility for guiding readers. Also, migrate from reStructuredText to Markdown.
Screenshots
Details
Before
After