docs: website docs structure + first content pages
Phase D foundation. Configures the pragmatic four-section sidebar (Getting started / Guides / Reference / Concepts) and replaces the template example pages with grounded content built on the shared "library" example database (authors/books/members/loans): - Getting started: installation, first project, simple vs advanced, the example library. - Reference: Types (all ten + serial/shortid + advanced aliases), Tables (create/drop, compound PK, advanced CREATE TABLE). - Concepts: projects & storage (readable files, derived database, autosave, temp projects). - Guides: Build the library (draft, to be refined for teaching). Command syntax grounded in en-US.yaml usage/help, command.rs, and types.rs (verified against tests). Records the settled doc decisions in STYLE.md. Build green (10 pages, Pagefind); content clean of "DSL"/engine-name.
This commit is contained in:
claude@clouddev1
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: The example library
|
||||
description: The small library database used throughout these docs.
|
||||
sidebar:
|
||||
order: 4
|
||||
---
|
||||
|
||||
Most examples in this documentation use the same small database: a library
|
||||
with **authors**, **books**, **members**, and **loans**. Keeping one
|
||||
familiar set of tables makes it easier to focus on the concept each page is
|
||||
teaching.
|
||||
|
||||
## The tables
|
||||
|
||||
| Table | Columns |
|
||||
|---|---|
|
||||
| `authors` | `author_id` (serial, primary key), `name` (text), `birth_year` (int) |
|
||||
| `books` | `book_id` (serial, primary key), `title` (text), `author_id` (int → authors), `published` (int), `isbn` (text, unique) |
|
||||
| `members` | `member_id` (serial, primary key), `name` (text), `joined` (date) |
|
||||
| `loans` | `loan_id` (serial, primary key), `book_id` (int → books), `member_id` (int → members), `loaned_on` (date), `returned_on` (date) |
|
||||
|
||||
## The relationships
|
||||
|
||||
- **An author has many books.** `books.author_id` points at
|
||||
`authors.author_id` — a one-to-many relationship.
|
||||
- **Members borrow books.** Each row in `loans` ties one book to one member,
|
||||
so `loans` connects `books` and `members` — a many-to-many relationship
|
||||
expressed through a bridging table.
|
||||
|
||||
You will build these tables and relationships step by step in
|
||||
[Build the library](/guides/build-the-library/). Individual reference pages
|
||||
use whichever part of this schema illustrates the command at hand.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Your first project
|
||||
description: Create a table, add a row, and look at it — a two-minute tour of the playground.
|
||||
sidebar:
|
||||
order: 2
|
||||
---
|
||||
|
||||
This is the shortest possible tour: create a table, put a row in it, and
|
||||
look at the result. Everything here is in **simple mode**, which is how the
|
||||
playground starts.
|
||||
|
||||
When you launch `rdbms-playground` with no arguments, it opens a fresh
|
||||
temporary project for you. Type commands into the input field at the bottom
|
||||
and press <kbd>Enter</kbd> to run them.
|
||||
|
||||
## Create a table
|
||||
|
||||
A table needs at least a primary key. The `with pk` clause names the
|
||||
primary-key column and its type:
|
||||
|
||||
```text
|
||||
create table authors with pk author_id(serial)
|
||||
```
|
||||
|
||||
`serial` is an auto-incrementing number — you will not have to fill it in
|
||||
yourself.
|
||||
|
||||
## Add a couple of columns
|
||||
|
||||
In simple mode you create a table with its key, then add the other columns
|
||||
one at a time:
|
||||
|
||||
```text
|
||||
add column to authors: name (text)
|
||||
add column to authors: birth_year (int)
|
||||
```
|
||||
|
||||
## Add a row
|
||||
|
||||
`insert` adds a row. List the columns you are supplying — the `author_id`
|
||||
fills itself in because it is a `serial`:
|
||||
|
||||
```text
|
||||
insert into authors (name, birth_year) values ('Ada Lovelace', 1815)
|
||||
```
|
||||
|
||||
The playground shows the row it just inserted, including the generated
|
||||
`author_id`.
|
||||
|
||||
## Look at the data
|
||||
|
||||
```text
|
||||
show data authors
|
||||
```
|
||||
|
||||
That is the whole loop: **create → add columns → insert → show**. From here:
|
||||
|
||||
- Build the full example database in [Build the library](/guides/build-the-library/).
|
||||
- Learn how [simple and advanced modes](/getting-started/modes/) differ.
|
||||
- Look up any command in the [Reference](/reference/types/).
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Install RDBMS Playground from a prebuilt binary or a package manager, and run it for the first time.
|
||||
sidebar:
|
||||
order: 1
|
||||
---
|
||||
|
||||
RDBMS Playground is a single self-contained program. There is nothing to
|
||||
configure and no separate database to install — everything it needs is
|
||||
built in.
|
||||
|
||||
## Prebuilt binaries
|
||||
|
||||
Download the binary for your platform, make it executable if needed, and
|
||||
put it somewhere on your `PATH`.
|
||||
|
||||
:::note
|
||||
Download links are published with each release. They are added here when the
|
||||
first public version ships.
|
||||
:::
|
||||
|
||||
## Package managers
|
||||
|
||||
Once published, the playground will be installable through common package
|
||||
managers:
|
||||
|
||||
```sh
|
||||
# macOS / Linux (Homebrew)
|
||||
brew install rdbms-playground
|
||||
|
||||
# Windows (Scoop)
|
||||
scoop install rdbms-playground
|
||||
```
|
||||
|
||||
:::note
|
||||
Package-manager availability lands with the first public release; the exact
|
||||
names are confirmed here at that time.
|
||||
:::
|
||||
|
||||
## Run it
|
||||
|
||||
Start the playground with no arguments and it opens a fresh, automatically
|
||||
named temporary project so you can start experimenting immediately:
|
||||
|
||||
```sh
|
||||
rdbms-playground
|
||||
```
|
||||
|
||||
To open an existing project, pass its path:
|
||||
|
||||
```sh
|
||||
rdbms-playground path/to/project
|
||||
```
|
||||
|
||||
Useful options (run `rdbms-playground --help` for the full list):
|
||||
|
||||
| Option | What it does |
|
||||
|---|---|
|
||||
| `--resume` | Reopen the most recently used project. |
|
||||
| `--data-dir <PATH>` | Use a different location for stored projects. |
|
||||
| `--theme <light\|dark>` | Force a theme instead of auto-detecting. |
|
||||
| `--mode <simple\|advanced>` | Start in a specific input mode. |
|
||||
|
||||
Next: [create your first project](/getting-started/first-project/).
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Simple and advanced modes
|
||||
description: How the playground's two input modes differ, how to switch, and the one-line escape hatch.
|
||||
sidebar:
|
||||
order: 3
|
||||
---
|
||||
|
||||
The playground has two input modes. You can do everything a beginner needs
|
||||
in **simple mode**, and reach for **advanced mode** when you want full SQL.
|
||||
|
||||
## Simple mode (the default)
|
||||
|
||||
Simple mode is a friendly, keyword-based command language designed for
|
||||
learning. Commands read close to English:
|
||||
|
||||
```text
|
||||
create table authors with pk author_id(serial)
|
||||
show data authors
|
||||
```
|
||||
|
||||
Simple mode accepts these learning commands plus the app-level commands
|
||||
(like `save`, `undo`, and `help`). If you type raw SQL here, the playground
|
||||
gently points you at advanced mode instead of failing silently.
|
||||
|
||||
## Advanced mode (SQL)
|
||||
|
||||
Advanced mode accepts standard SQL — `SELECT`, `INSERT`, `CREATE TABLE`, and
|
||||
more — alongside the same app-level commands:
|
||||
|
||||
```sql
|
||||
select title, published from books where published >= 2000 order by published;
|
||||
```
|
||||
|
||||
Switch modes with the `mode` command:
|
||||
|
||||
```text
|
||||
mode advanced
|
||||
mode simple
|
||||
```
|
||||
|
||||
The mode you leave a project in is remembered and restored the next time you
|
||||
open it, so a project set up for SQL practice reopens in advanced mode.
|
||||
|
||||
## The one-line escape
|
||||
|
||||
When you are in simple mode and want to run a single SQL statement without
|
||||
switching, prefix the line with a colon:
|
||||
|
||||
```text
|
||||
:select count(*) from books
|
||||
```
|
||||
|
||||
That runs just this one line as SQL; you stay in simple mode afterwards.
|
||||
|
||||
## Seeing the SQL behind a command
|
||||
|
||||
When you run a simple-mode command in advanced mode, the playground prints
|
||||
the equivalent SQL beneath your command. It is a built-in way to learn how
|
||||
the friendly commands map onto real SQL — the same statements you could type
|
||||
yourself in advanced mode.
|
||||
Reference in New Issue
Block a user