Naming things: {learn,usage}.md -> tutorial.md
#250
Conversation
amotl
added
sanding-1200
|
Warning Rate limit exceeded@amotl has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 15 minutes and 41 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 (18)
WalkthroughDocumentation navigation updated by replacing “learn” toctree entries with “Tutorial ” across multiple index pages. One page (dbt) also adds a brief “Usage guidelines, notes, and advanced configuration options.” content block. No code, APIs, or logic changed. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related issues
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
changed the title
learn.md -> tutorial.md{learn,usage}.md -> tutorial.md
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
docs/feature/document/index.md(1 hunks)docs/feature/search/fts/index.md(1 hunks)docs/integrate/azure-functions/index.md(1 hunks)docs/integrate/dbt/index.md(1 hunks)docs/integrate/grafana/index.md(1 hunks)docs/integrate/influxdb/index.md(1 hunks)docs/integrate/marquez/index.md(1 hunks)docs/integrate/metabase/index.md(1 hunks)docs/integrate/mongodb/index.md(1 hunks)docs/integrate/streamsets/index.md(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/integrate/influxdb/index.mddocs/integrate/azure-functions/index.mddocs/integrate/grafana/index.mddocs/integrate/mongodb/index.mddocs/integrate/streamsets/index.mddocs/integrate/dbt/index.md
🪛 LanguageTool
docs/integrate/metabase/index.md
[grammar] ~72-~72: There might be a mistake here.
Context: ...maxdepth: 1 :hidden: Tutorial ::: ```{seealso} [CrateDB and Metabase]...
(QB_NEW_EN)
docs/integrate/influxdb/index.md
[grammar] ~66-~66: There might be a mistake here.
Context: ...maxdepth: 1 :hidden: Tutorial :::
(QB_NEW_EN)
docs/integrate/marquez/index.md
[grammar] ~45-~45: There might be a mistake here.
Context: ...::{toctree} :hidden: Tutorial ::: [Marquez]: https://marquezproject....
(QB_NEW_EN)
docs/feature/search/fts/index.md
[grammar] ~377-~377: There might be a mistake here.
Context: ...n: options analyzer Tutorial ::: [BM25: The Next Generation of Luce...
(QB_NEW_EN)
docs/integrate/azure-functions/index.md
[grammar] ~45-~45: There might be a mistake here.
Context: ...maxdepth: 1 :hidden: Tutorial ::: [Azure Functions]: https://azure.m...
(QB_NEW_EN)
docs/integrate/grafana/index.md
[grammar] ~58-~58: There might be a mistake here.
Context: ...maxdepth: 1 :hidden: Tutorial ::: ```{seealso} [CrateDB and Grafana]...
(QB_NEW_EN)
docs/integrate/mongodb/index.md
[grammar] ~96-~96: There might be a mistake here.
Context: ...maxdepth: 1 :hidden: Tutorial ::: :::{seealso} Blog: [Announcing...
(QB_NEW_EN)
docs/integrate/streamsets/index.md
[grammar] ~39-~39: There might be a mistake here.
Context: ...maxdepth: 1 :hidden: Tutorial ::: [StreamSets Data Collector]: https:...
(QB_NEW_EN)
🔇 Additional comments (11)
docs/integrate/influxdb/index.md (1)
66-66: Update looks good — tutorial and legacy label verified
- docs/integrate/influxdb/tutorial.md — present; contains the legacy label
(influxdb-learn)=on line 1.No further action required.
docs/integrate/grafana/index.md (1)
58-58: Tutorial target exists — please run the docs build to confirm resolutionFound the target file; please confirm the Sphinx build resolves the toctree entry.
- docs/integrate/grafana/index.md — toctree entry:
Tutorial <tutorial>- docs/integrate/grafana/tutorial.rst — verified present
Snippet:
Tutorial <tutorial>docs/integrate/mongodb/index.md (1)
96-96: Tutorial exists and legacy label retained — no action requiredThe tutorial file docs/integrate/mongodb/tutorial.md exists and contains the legacy label (mongodb-learn)= on line 5, so the toctree/grid-card refs are correct.
- docs/integrate/mongodb/tutorial.md — (mongodb-learn)= at line 5
docs/feature/document/index.md (1)
430-431: Toctree label/target update looks good.Switching to "Tutorial " aligns with the PR objective and MyST/Sphinx toctree syntax.
docs/feature/search/fts/index.md (1)
377-378: Toctree updated correctly to “Tutorial ”.The change is syntactically correct within the existing toctree block. No further issues spotted here.
docs/integrate/marquez/index.md (2)
45-46: Toctree entry update looks correct.Hidden toctree now points to the tutorial target as intended.
34-39: No change required —marquez-learnlabel is presentdocs/integrate/marquez/tutorial.md starts with (marquez-learn)=, so the 🔗 marquez-learn in docs/integrate/marquez/index.md is valid.
Files with other
:link: *-learnoccurrences (recommend scanning those targets):
- docs/integrate/streamsets/index.md
- docs/integrate/azure-functions/index.md
- docs/integrate/mongodb/index.md
- docs/integrate/marquez/index.md
- docs/integrate/influxdb/index.md
If you want, I can scan the corresponding tutorial files and prepare a patch to replace any missing legacy labels or convert links to doc-by-name.
Likely an incorrect or invalid review comment.
docs/integrate/streamsets/index.md (2)
39-40: Toctree entry update is correct.The hidden toctree now targets the tutorial page as per the naming change.
27-33: Card link is valid — no change requiredVerified that the tutorial defines the anchor and the index references it, so the card link will resolve.
- docs/integrate/streamsets/tutorial.rst — contains
.. _streamsets-learn:(line 1)- docs/integrate/streamsets/index.md — uses
:link: streamsets-learn(line 28)Remove the suggested doc-name diff; keep the existing
:link: streamsets-learnas-is.docs/integrate/dbt/index.md (2)
145-149: Toctree re-targeting and new content block look good.
- Swapping to “Tutorial ” is correct.
- The “+++” separator for card body content is valid in sphinx-design and reads well.
131-140: No change required — legacy anchor preservedFound (dbt-usage)= in docs/integrate/dbt/tutorial.md:1, so the 🔗 dbt-usage (ref) in docs/integrate/dbt/index.md is valid — no update needed.
- docs/integrate/dbt/tutorial.md:1 — contains "(dbt-usage)="
- docs/integrate/dbt/index.md: ~132 — grid-item-card uses ":link: dbt-usage" (ref)
Do not apply the suggested refactor; keep the existing anchor and link as-is.
There was a problem hiding this comment.
Proposed rewrite rule.
rewrite ^/docs/guide/integrate/(.*)/(learn|usage).html$ /docs/guide/integrate/$1/tutorial.html redirect;There was a problem hiding this comment.
Added to the set of redirects for the current iteration.
There was a problem hiding this comment.
Proposed rewrite rule.
rewrite ^/docs/guide/feature/(.*)/(learn|usage).html$ /docs/guide/feature/$1/tutorial.html redirect;There was a problem hiding this comment.
Added to the set of redirects for the current iteration.
amotl
force-pushed
the
layout-integrate-strip-prefix
branch
from
ea49305 to
f6223a3
Compare
|
It's good that we nailed the "naming things" for this particular detail. However, a few questions on harmonization details remain, and I would love to present them to you to possibly receive a pragmatic decision out of it. 1 Thanks!
Footnotes
|
amotl
force-pushed
the
layout-integrate-strip-prefix
branch
from
96ab2bb to
2426269
Compare
amotl
force-pushed
the
layout-learn-tutorial
branch
from
8009e8c to
c27d627
Compare
amotl
force-pushed
the
layout-learn-tutorial
branch
from
c27d627 to
db89bb5
Compare
3 participants
About
A sweeping update to use a different file name for the tutorial pages:
tutorial{.md,.rst}.Preview
Not much to "see" here. -- https://cratedb-guide--250.org.readthedocs.build/integrate/
References