Skip to content

Refine "home" and "connect" entry point pages #237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 12, 2025
Merged

Refine "home" and "connect" entry point pages #237

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
56fd4a2
Content: Refine main and "connect" entry point pages
amotl Aug 9, 2025
41f631f
Project: Refine README and DEVELOP documents
amotl Aug 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions DEVELOP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
# Developer Guide

To set up a development sandbox and build the docs with live reloading
functionality, type `make dev` in a terminal while inside the `docs` folder.
Please refer to the [Authoring Guide] for more information.
functionality, clone the repository, then type `make dev` in a terminal
from within the `docs` folder.

[Authoring Guide]: https://crate-docs-theme.readthedocs.io/en/latest/authoring.html
```shell
git clone https://github.com/crate/cratedb-guide.git
cd cratedb-guide/docs
make dev
```
38 changes: 28 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,32 +27,48 @@

</div>


## 👨‍💻 Usage
## 👨‍💻 About

- This repository contains the sources for the documentation pages rendered
to https://cratedb.com/docs/guide/. The content is optimally consumed
from there.

- If you are looking for something specific, please use the search
feature, for example, [searching for "flink"].

- You can use the content and code snippets for educational and knowledge base
purposes, or as blueprints for your own projects.


## 🧐 What's Inside

- Sources for statically rendered documentation about CrateDB written in
[Markdown] and/or [reStructuredText].
The main content tree of the CrateDB Guide includes a wide array of topics.

If you are looking for something specific, please use the search feature on
GitHub, for example, [searching for "flink"], or clone the repository and
use a local search tool like `ripgrep` or the Silver Searcher.

Comment on lines +41 to +46
Copy link

@coderabbitai coderabbitai bot Aug 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix mismatch between “GitHub search” wording and the linked target

The sentence says “use the search feature on GitHub” but the link reference points to the docs site search. Align the target with the wording by pointing to GitHub Code Search.

Apply this diff to update the link reference:

-[searching for "flink"]: https://cratedb.com/docs/guide/search.html?q=flink
+[searching for "flink"]: https://github.com/search?q=repo%3Acrate%2Fcratedb-guide%20flink&type=code

Also applies to: 97-97, 104-104

🤖 Prompt for AI Agents 
In README.md around lines 41 to 46 (and also lines 97 and 104), the text says
“use the search feature on GitHub” but the linked URL currently points to the
docs site search; update the link target to GitHub Code Search
(https://github.com/search) so the wording and link match, and apply the same
replacement for the other occurrences at lines 97 and 104.

### ℹ️ General information

- Sources for statically rendered documentation about CrateDB are written in
[Markdown] and/or [reStructuredText]. Please prefer using Markdown going forward.
- The documentation system is based on [Sphinx], [MyST], [sphinx-design],
[sphinx-design-elements], and many other Sphinx addons and plugins.

- The documentation theme is [crate-docs-theme].

- The project uses [Read the Docs] for publishing.

### 📁 Directory layout

The folder structure follows a few conventions and ideas. The order of the items
enumerated below is the order how they are currently enumerated within the primary
navigation element (left-hand menu).

- `start` The canonical "Getting Started" section, providing an easy user journey.
- `install` The canonical "How to install CrateDB" section.
- `connect` The canonical "How to connect to CrateDB" section.
- `feature` A backbone section about all features at a glance, using a flat layout.
- `ingest` A category section bundling all ingest methods.
- `topic` A category section bundling different topics [sic!] and application domains.
- `use` A category section bundling different successful customer scenarios.
- `integrate` A backbone section about all the integration items, using a flat layout.
- `admin` A potpourri of operational guidelines.
- `performance` A potpourri of performance tuning guidelines.

## 💁 Contributing

Expand All @@ -67,6 +83,7 @@ Your bug reports, feature requests, and patches are highly appreciated.
See also the [developer docs] to learn how to set up a development sandbox, in
order to start editing. The [contribution docs] include general information
about how to contribute to CrateDB repositories.
Please also refer to the [CrateDB Authoring Guide] for more information.


## 🌟 Contributors
Expand All @@ -77,6 +94,7 @@ about how to contribute to CrateDB repositories.

[contribution docs]: https://github.com/crate/crate/blob/master/CONTRIBUTING.rst
[CrateDB]: https://github.com/crate/crate
[CrateDB Authoring Guide]: https://crate-docs-theme.readthedocs.io/en/latest/authoring.html
[crate-docs-theme]: https://crate-docs-theme.readthedocs.io/
[developer docs]: DEVELOP.md
[Markdown]: https://daringfireball.net/projects/markdown/
Expand Down
22 changes: 14 additions & 8 deletions docs/connect/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,29 +70,35 @@ protocol.
:padding: 0
:gutter: 2

::::{grid-item-card} {material-outlined}`lightbulb;2em` General information
::::{grid-item-card} {material-outlined}`link;2em` How to connect
- {ref}`connect-configure`

To connect to CrateDB, your application or driver needs to be configured
with corresponding database URI and connection properties.

- {ref}`connect-drivers`
- {ref}`CLI programs <connect-cli>`

All available CrateDB drivers and adapters for supported programming languages,
frameworks, and environments.
Use CLI programs to connect to CrateDB.

- {ref}`Database IDEs <connect-ide>`

Use IDEs to connect to CrateDB.
+++
Database connectivity information.
Database connectivity options and tools.
::::

::::{grid-item-card} {material-outlined}`lightbulb;2em` How to connect
:width: auto
::::{grid-item-card} {material-outlined}`not_started;2em` How to use database drivers
- {ref}`connect-java`
- {ref}`connect-javascript`
- {ref}`connect-php`
- {ref}`connect-python`
- {ref}`connect-ruby`
- {ref}`connect-drivers`

All available CrateDB drivers and adapters for supported programming languages,
frameworks, and environments.
+++
Connection examples.
Database driver connection examples.
::::

:::::
Expand Down
Loading