Layout NG: Folder structure and naming things #236
Conversation
amotl
added
sanding-180
|
Warning Rate limit exceeded@amotl has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 13 minutes and 43 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 (20)
WalkthroughThis update restructures and simplifies the documentation navigation and content. It replaces many Sphinx Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant DocsIndex
participant TopicIndex
participant UseIndex
User->>DocsIndex: Navigate to documentation
DocsIndex->>TopicIndex: Show available topics (new page)
DocsIndex->>UseIndex: Show use cases (revised content)
TopicIndex->>User: Display topic grid and links
UseIndex->>User: Display streamlined use cases and reference architectures
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 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 (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🔭 Outside diff range comments (4)
docs/ingest/cdc/index.md (1)
55-63: Duplicate AWS DMS description; remove repetitionThe “AWS DMS supports migration between 20-plus…” sentence appears twice back-to-back. Please deduplicate.
- It supports migration between 20-plus database and analytics engines. - -AWS DMS supports migration between 20-plus database and analytics engines, either -on-premises, or per EC2 instance databases. Supported data migration sources are: +It supports migration between 20+ database and analytics engines, either +on-premises or per EC2 instance databases. Supported data migration sources are:docs/index.md (2)
86-90: Rename “Application Domains” to “Topics” for consistencyAligns the homepage section with the repo-wide terminology change.
-## Application Domains +## Topics
287-299: Stale Reference Architectures card needs removal or retargetingThe
reference-architecturespage no longer exists (nodocs/reference-architectures), but there is an Industrial use-case section underdocs/use/industrial. Update or remove this card.• File: docs/index.md (lines ≈287–299)
• Option A — remove the card entirely
• Option B — retarget to the Industrial page:-:::{grid-item-card} Reference Architectures -:link: reference-architectures -:link-alt: Reference Architectures with CrateDB +:grid-item-card} Industrial Reference Architectures +:link: use/industrial +:link-alt: Industrial Reference Architectures with CrateDBdocs/ingest/etl/index.md (1)
59-63: Remove duplicated “AWS DMS supports …” sentenceSame repetition as in CDC page; simplify and tighten.
-AWS DMS supports migration between 20-plus database and analytics engines, either -on-premises, or per EC2 instance databases. Supported data migration sources are: +It supports migration between 20+ database and analytics engines, either on-premises +or per EC2 instance databases. Supported data migration sources are:
🧹 Nitpick comments (4)
docs/use/industrial/azure-iot.rst (1)
1-3: Consider adding a page-level label for stable cross-referencesAdding a document label avoids relying on path-based refs and helps with future moves/renames.
Example (place above the title):
.. _azure-iot: ====================== Azure IoT with CrateDB ======================docs/use/industrial/index.md (1)
56-57: Minor copy edit for concision and stylePrefer “various use cases” over “a variety of use-cases”.
-Reference architectures illustrating how CrateDB can be used in a variety of -use-cases. +Reference architectures showing how CrateDB can be used in various use cases.docs/ingest/cdc/index.md (1)
11-12: Minor copy editRemove the comma after “components”.
-CrateDB also provides a few native adapter components, that can be used +CrateDB also provides a few native adapter components that can be useddocs/use/index.md (1)
6-9: Hyphenation and wording nits (“Long-term”, “multi-tenant”)Use hyphens for compound adjectives and fix “multi tenant”.
-{tags-primary}`Long Term Metrics Store` +{tags-primary}`Long-term Metrics Store` ... -:::{grid-item-card} {material-outlined}`manage_history;2em` Long Term Metrics Store +:::{grid-item-card} {material-outlined}`manage_history;2em` Long-term Metrics Store ... -Store metrics and telemetry data for the long term, with the benefits of +Store metrics and telemetry data for the long-term, with the benefits of ... -Learn how others are successfully running real-time multi tenant data +Learn how others are successfully running real-time multi-tenant dataAlso applies to: 52-56, 57-59, 62-64
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (19)
docs/connect/ide.md(1 hunks)docs/connect/index.md(1 hunks)docs/index.md(1 hunks)docs/ingest/cdc/index.md(1 hunks)docs/ingest/etl/index.md(6 hunks)docs/ingest/index.md(1 hunks)docs/ingest/telemetry/index.md(1 hunks)docs/integrate/index.md(1 hunks)docs/integrate/metabase/index.md(1 hunks)docs/integrate/rill/index.md(1 hunks)docs/reference-architectures/index.rst(0 hunks)docs/topic/bi/index.md(1 hunks)docs/topic/framework/index.md(1 hunks)docs/topic/index.md(1 hunks)docs/topic/lineage/index.md(1 hunks)docs/topic/visualize/index.md(1 hunks)docs/use/index.md(2 hunks)docs/use/industrial/azure-iot.rst(1 hunks)docs/use/industrial/index.md(1 hunks)
💤 Files with no reviewable changes (1)
- docs/reference-architectures/index.rst
🧰 Additional context used
🧠 Learnings (12)
📓 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.
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
📚 Learning: 2025-08-08T16:50:14.965Z
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Applied to files:
docs/use/industrial/azure-iot.rstdocs/topic/visualize/index.mddocs/use/industrial/index.mddocs/topic/lineage/index.mddocs/index.mddocs/ingest/etl/index.mddocs/topic/index.mddocs/use/index.mddocs/integrate/index.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
Learning: In the CrateDB Guide repository, intersphinx mappings like "cloud" are defined within the root project `crate-docs-theme` and inherited by the documentation projects, so they don't need to be explicitly defined in individual `docs/conf.py` files.
Applied to files:
docs/use/industrial/azure-iot.rstdocs/topic/visualize/index.mddocs/use/industrial/index.mddocs/topic/lineage/index.mddocs/ingest/etl/index.mddocs/topic/index.mddocs/integrate/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/integrate/rill/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/integrate/rill/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 rubric directive is used for informal headings and doesn't wrap content. The correct syntax is:
```
:::{rubric} Title
:::
```
followed by the content outside of the directive. This differs from admonition blocks which do wrap their content.
Applied to files:
docs/integrate/rill/index.md
📚 Learning: 2025-05-18T12:50:38.681Z
Learnt from: amotl
PR: crate/cratedb-guide#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.
Applied to files:
docs/ingest/index.mddocs/connect/ide.mddocs/topic/visualize/index.mddocs/use/industrial/index.mddocs/topic/lineage/index.mddocs/ingest/etl/index.mddocs/topic/index.mddocs/use/index.mddocs/integrate/index.md
📚 Learning: 2025-05-18T12:50:36.393Z
Learnt from: amotl
PR: crate/cratedb-guide#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/connect/ide.mddocs/topic/visualize/index.mddocs/use/industrial/index.mddocs/topic/lineage/index.mddocs/ingest/cdc/index.mddocs/ingest/etl/index.mddocs/topic/index.mddocs/use/index.mddocs/integrate/index.md
📚 Learning: 2025-06-05T14:29:15.512Z
Learnt from: amotl
PR: crate/cratedb-guide#207
File: docs/integrate/etl/iceberg-risingwave.md:205-207
Timestamp: 2025-06-05T14:29:15.512Z
Learning: The `records.Database("crate://", echo=True)` connection string for CrateDB works with defaults: localhost as host, "crate" as user, and blank password. This is valid and functional code in the records library.
Applied to files:
docs/connect/ide.md
📚 Learning: 2025-08-06T02:11:46.794Z
Learnt from: amotl
PR: crate/cratedb-guide#222
File: docs/integrate/powerbi/index.md:16-23
Timestamp: 2025-08-06T02:11:46.794Z
Learning: The `project:` role in MyST Markdown syntax like `[](project:#powerbi-desktop)` and `[](project:#powerbi-service)` is valid cross-reference syntax in the CrateDB Guide repository's MyST Markdown setup.
Applied to files:
docs/connect/ide.mddocs/use/industrial/index.mddocs/topic/bi/index.mddocs/ingest/etl/index.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
Applied to files:
docs/topic/visualize/index.mddocs/use/industrial/index.mddocs/topic/lineage/index.mddocs/ingest/etl/index.mddocs/topic/index.mddocs/integrate/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/topic/visualize/index.mddocs/topic/lineage/index.mddocs/topic/index.mddocs/use/index.mddocs/integrate/index.md
🪛 LanguageTool
docs/use/industrial/index.md
[style] ~56-~56: Consider using a more concise synonym.
Context: ...illustrating how CrateDB can be used in a variety of use-cases. :::{toctree} :maxdepth: 1 ...
(A_VARIETY_OF)
docs/use/index.md
[uncategorized] ~8-~8: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...primary}Industrial Data {tags-primary}Long Term Metrics Store ::: :::{rubric} Traditi...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[uncategorized] ~52-~52: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...{material-outlined}manage_history;2em Long Term Metrics Store 🔗 metrics-store :lin...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 markdownlint-cli2 (0.17.2)
docs/topic/index.md
73-73: Link fragments should be valid
(MD051, link-fragments)
74-74: Link fragments should be valid
(MD051, link-fragments)
75-75: Link fragments should be valid
(MD051, link-fragments)
76-76: Link fragments should be valid
(MD051, link-fragments)
77-77: Link fragments should be valid
(MD051, link-fragments)
⏰ 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 (21)
docs/use/industrial/azure-iot.rst (1)
1-3: Title rename LGTMClearer, consistent with the new navigation. No content issues spotted.
docs/use/industrial/index.md (1)
62-64: Toctree target “distributed-ml” confirmed
The filedocs/use/industrial/distributed-ml.rstexists alongsideazure-iot.rst, so the reference is valid. No changes needed.docs/integrate/rill/index.md (1)
1-1: Anchor addition LGTMLabel
(rill)=is correct MyST syntax and aligns with the new linking strategy.docs/ingest/index.md (1)
71-78: Hidden toctree targets verifiedAll three ingest sub-index files exist under
docs/ingestand include the expected MyST anchors for{ref}usage:
docs/ingest/etl/index.md:(etl)=docs/ingest/cdc/index.md:(cdc)=docs/ingest/telemetry/index.md:(telemetry)=LGTM!
docs/ingest/telemetry/index.md (2)
15-15: Prometheus reference verified• MyST label
(prometheus)=is defined indocs/integrate/prometheus/index.md:1
No further changes needed.
19-19: Telegraf{ref}label verified
The MyST labeltelegrafis defined indocs/integrate/telegraf/index.mdat line 1. The{ref}usage is correct—no further changes needed.docs/topic/lineage/index.md (1)
41-41: ✅ Cross-ref valid – no changes neededThe
(marquez)=label is defined in docs/integrate/marquez/index.md, so the{ref}link in docs/topic/lineage/index.md resolves correctly.docs/connect/index.md (1)
105-106: IDE page integration verifiedConfirmed that
docs/connect/ide.mdexists and contains the# Database IDEsheading. LGTM—approving the changes.docs/topic/framework/index.md (1)
25-29: Confirmed: all{ref}labels resolve correctlyAll five labels (
django,gradio,plotly,pyviz,streamlit) are defined in their respectivedocs/integrate/.../index.mdfiles. No changes needed.docs/integrate/metabase/index.md (1)
1-1: No duplicate(metabase)=label found
Anchor(metabase)=in docs/integrate/metabase/index.md:1 enables stable refs and is unique across the repo. Looks good.docs/connect/ide.md (2)
8-11: Target label exists for DataGrip
The(datagrip)label is defined indocs/integrate/datagrip/index.md(line 1), so the{ref}todatagripis valid. No further changes needed.
12-15: Cross-reference target verified
- Found the label
(dbeaver)=indocs/integrate/dbeaver/index.mdon line 1.- The
{ref}todbeaverindocs/connect/ide.mdis valid; no changes needed.docs/topic/bi/index.md (1)
13-21: All BI ref labels are present
Verified that(powerbi)=,(rill)=, and(tableau)=labels exist in thedocs/files. No build errors expected.docs/ingest/cdc/index.md (1)
59-60: Debezium reference label is present
- Confirmed the
(debezium)=label in docs/integrate/debezium/index.md (line 1), so the{ref}debezium` link in docs/ingest/cdc/index.md resolves correctly.docs/ingest/etl/index.md (1)
4-4: Heading update LGTMClearer with “(ETL)” added.
docs/topic/visualize/index.md (1)
11-18: All visualization references verified — no changes needed
All{ref}targets (cluvio,explo,grafana,metabase,plotly,pyviz,superset) exist in the docs (an unusedapache-supersetanchor is also present). No action required.docs/use/index.md (2)
52-56: Ref target “metrics-store” confirmedThe MyST label
(metrics-store)=exists in the repository at:
docs/use/telemetry/index.md:1No further changes required.
70-78: Telemetry use-case path is correct; no toctree update neededThe entry
telemetry/indexindocs/use/index.mdstill points to an existing file (docs/use/telemetry/index.md). The PR only moved the integration topic underdocs/ingest/telemetry/index.md—it did not relocate the use-case content. You can safely ignore the suggested change.• File: docs/use/index.md (lines 70–78): keep
:maxdepth: 1 :hidden: analytics/index industrial/index telemetry/index ← remains valid migrate/indexLikely an incorrect or invalid review comment.
docs/integrate/index.md (1)
16-52: All integration pages present—no broken links
Ran a script to confirm that everydocs/integrate/<name>/index.mdexists for each toctree entry. All 32 entries are OK—no missing pages or build warnings expected.docs/topic/index.md (2)
1-3: Back-compat anchors retained (domain/domains) — nice touchKeeping old labels avoids breaking inbound links after the rename.
41-66: Ref link targets verifiedBoth
:link-type: reftargets indocs/topic/index.mdexist:
(timeseries)=indocs/topic/timeseries/index.md:1(machine-learning)=indocs/topic/ml/index.md:3No further changes needed.
The new structure revolves around "Topics", "Use Cases", and "Ingest".
Existing pages are relocated appropriately, specifically category-like
pages that provide guidance into relevant subsections.
- The "Application Domains" label is discouraged, let's just use "Topic"
instead: s/domain/topic/
- Refactor category sections from `integrate/{etl,cdc,telemetry}` to
`ingest`
- Refactor category sections and pages from
`integrate/{bi,framework,lineage,testing,timeseries,visualize}` to
`topic`
- Dissolve `reference-architectures` folder, refactor contents to
`use/industrial`
2 participants
About
The patch concludes a few page relocations based on the currently proposed next-generation layout. It already takes a few "naming things" requests into account that came up recently.
The structural changes revolve around "Ingest", "Topics", and "Use Cases". Existing pages are relocated appropriately, specifically category-like pages that provide guidance into relevant subsections, but also leaf-node pages that elaborate about them in more detail. The new
ingestsubsection is becoming a spot of increased gravity.Details
s/domain/topic/.integrate/{etl,cdc,telemetry}toingest.integrate/{bi,framework,lineage,testing,timeseries,visualize}totopic.reference-architecturesfolder, refactor its ingredients touse/industrial.Preview
References