Connect: Reorganize and clean up section

[amotl]

About

This patch sets the stage for improved guidance within the drivers section, as suggested. It is just a little reorg plus some minor copy-editing. Further improvements as discussed will be submitted using a subsequent patch.

Preview

• https://cratedb-guide--361.org.readthedocs.build/connect/

References

• Improve general guidance aka. easy user journey #227
• https://github.com/crate/tech-content/issues/124

[coderabbitai]

Walkthrough

Reorganizes and expands docs under docs/connect: replaces legacy pages (connect, ide, df/index, orm) with a drivers‑focused index, expands Applications and Python driver pages, adds a natural‑language integration page, and updates general information anchors and heading levels.

Changes

Cohort / File(s)	Summary of Changes
Connect index overhaul docs/connect/index.md	Reworked landing into "Connect / Drivers": new Get started, drivers grid (Java, JavaScript, PHP, Python, Ruby), updated toctree and layout/styling.
Applications doc expansion docs/connect/application.md	Added/rewrote Applications, CrateDB Admin UI, CrateDB Shell, Command-line programs (crash, psql, HTTPie, curl), Database IDEs (DataGrip, DBeaver); heading-level adjustments, images, and notes.
Python drivers reorganization docs/connect/python.md	Reorganized into Official/Community drivers, added crate-python under Official and cratedb-async under Community; SQLAlchemy and Dataframe libs (Dask, pandas, Polars) restructured and cross-referenced.
Natural language integration (new) docs/connect/natural.md	New page introducing text-to-SQL integrations (LlamaIndex, MCP) with references to CrateDB and CrateDB Cloud.
General information tweaks docs/connect/general.md	Renamed top heading to "General information", kept include for links, added anchors for authentication, schemas, and superuser.
Removal of legacy pages docs/connect/connect.md, docs/connect/df/index.md, docs/connect/ide.md, docs/connect/orm.md	Deleted legacy Connect, DataFrame index, IDE, and ORM documentation pages and their contents.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Layout NG: Folder structure and naming things #236 — Overlapping edits to connect documentation and IDE/connect navigation.
• Polars: Index page #298 — Directly related to DataFrame docs changes / removal of docs/connect/df/index.md.
• Connect/Python: Add driver cratedb-async #229 — Related addition/movement of cratedb-async / Python driver docs.

Suggested labels

new content

Suggested reviewers

• bmunkholm
• kneth
• surister

Poem

I hop through files with curious cheer,
Cards rearranged, old pages clear.
New drivers shine, IDEs find home,
Docs pruned and planted — onward I roam. 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly communicates the main change of reorganizing and cleaning up the Connect section without excessive detail or irrelevant noise, matching the core intent of the pull request.
Description Check	✅ Passed	The description clearly describes the reorganization and minor copy edits of the drivers section, provides a preview link, and references related issues, making it directly relevant to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch connect-reorg

---

📜 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 f736045 and 6eff8b4.

📒 Files selected for processing (1)

• docs/connect/index.md (3 hunks)

⏰ 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

---

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.}

[bmunkholm]

On connect/index: Perhaps we should move "All drivers" card down to the end as it's not about "get started"? That lso fits the location in the TOC.

[bmunkholm]

In general, I'm not really sold on the concept of the links to the right at the top (and that's about all pages that has this. That could be handled separately, but might as well mention here again). The reason is my attention is drawn to them while reading the left column, not knowing what I'm missing out on and if I should investigate any of that before moving on.
So I would prefer that we in general have these references at the bottom for "more reading" after this.

I would in this case also remove "obvious" references to wikipedia and assume that's either common knowledge or that people can look it up themselves.
We could add some general guidelines about how to handle linking to the general author guidelines.

Perhaps this belongs more in a general issue...
@coderabbitai: create an issue about this.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Create a GitHub issue about documentation reference link placement

gh issue create \
  --title "Documentation UX: Reconsider placement and handling of reference links" \
  --body "## Problem

The current documentation approach places reference links on the right side at the top of pages (using side panels or similar layouts). This can be distracting for readers as it draws attention while reading the main content, creating uncertainty about what information might be missed.

## Proposed improvements

1. **Move reference links to the bottom**: Place reference links at the end of pages as \"more reading\" sections, allowing readers to focus on the main content first.

2. **Remove obvious references**: Eliminate links to common knowledge resources (e.g., Wikipedia entries for widely known concepts) and assume readers can look these up independently if needed.

3. **Create general guidelines**: Add guidance about reference linking to the general author guidelines to ensure consistency across documentation.

## Context

This affects multiple documentation pages across the crate/cratedb-guide repository. While this concern was raised during review of PR #361, it represents a broader documentation design principle that should be addressed systematically.

## References

- Related PR: https://github.com/crate/cratedb-guide/pull/361
- Original comment: https://github.com/crate/cratedb-guide/pull/361#discussion_r1909874231

/cc @bmunkholm" \
  --assignee bmunkholm

Length of output: 49

---

@bmunkholm: I've created issue #372 to track this documentation UX concern: #372

The issue captures your feedback about:

• Moving reference links from the top-right to the bottom as "more reading" sections
• Removing obvious references like Wikipedia links for common knowledge
• Adding general guidelines to the author guidelines

You're right that this is a broader concern affecting multiple pages and should be addressed systematically rather than being tied to this specific PR. The issue is assigned to you for further discussion and prioritization.

[amotl]

Hi Brian. If your concerns are mostly about the primary navigation, this is just a humble patch which already cleans up a few items there to set the stage for subsequent patches. In this spirit, it doesn't mean it is the final solution. Any item can be moved at your or other's disposal, not necessarily connected to this patch. Otherwise, if you have a quick wish for copy-editing on behalf of this very patch, please highlight it by adding an inline comment at the very spot you are referring to. General discussions, also as commandeered to CodeRabbit, could be added to the existing runsheet/tracking ticket instead of creating a separate issue.

• Improve general guidance aka. easy user journey #227

/cc @coderabbitai

[amotl]

@bmunkholm said:

Perhaps we should move "All drivers" card down to the end as it's not about "get started"? That lso fits the location in the TOC.

[amotl]

I don't know if this will look great. Maybe just remove it? Do you have another idea for the void it would create, to link to a different target?

[bmunkholm]

Agree, it likely won't look too good at the bottom :-(
Maybe we can live without it. It's in the TOC anyway. Yeah, I would vote for removing.

[amotl]

6eff8b4 removes the card.