Expand tooling documentation

Author: georgestagg

doc/CLAUDE.md

@@ -17,7 +17,7 @@ doc/
 │   ├── first_plot.qmd      Tutorial: first visualization
 │   ├── grammar.qmd         Grammar of Graphics conceptual foundation
 │   ├── anatomy.qmd         Anatomy of a ggsql query
-│   ├── tooling.qmd         VS Code / Positron / Jupyter / Python / R / CLI integrations
+│   ├── tooling/            VS Code / Positron / Jupyter / Python / R / CLI / Wasm
 │   └── the_rest.qmd        Advanced features
 ├── syntax/
 │   ├── index.qmd

doc/_quarto.yml

@@ -139,8 +139,22 @@ website:
           href: get_started/grammar.qmd
         - text: Anatomy of ggsql
           href: get_started/anatomy.qmd
-        - text: Tooling
-          href: get_started/tooling.qmd
+        - section: Tooling
+          contents:
+            - text: Overview
+              href: get_started/tooling/index.qmd
+            - text: Positron / VS Code
+              href: get_started/tooling/positron-vscode.qmd
+            - text: Jupyter & Quarto
+              href: get_started/tooling/jupyter-quarto.qmd
+            - text: CLI
+              href: get_started/tooling/cli.qmd
+            - text: Python
+              href: get_started/tooling/python.qmd
+            - text: R
+              href: get_started/tooling/r.qmd
+            - text: WebAssembly
+              href: get_started/tooling/webassembly.qmd
         - text: The rest of the owl
           href: get_started/the_rest.qmd
         - text: Wrap up

doc/assets/logos/javascript.svg

@@ -284,3 +284,16 @@ ggsql-jupyter --install
 
 For syntax highlighting and language support in VS Code or Positron, install the ggsql extension. You can either install it directly from the [extension marketplace](https://open-vsx.org/extension/ggsql/ggsql) from within the IDE or download and install it manually (in the *Extensions* view, click the `...` menu, select "Install from VSIX...", and choose the downloaded file.)
 :::
+
+::: {.icon-section}
+[![](../assets/logos/webassembly.svg){height=60} ![](../assets/logos/javascript.svg){height=60}]{.section-icons}
+
+## WebAssembly / JavaScript
+
+To use ggsql in a web application or JavaScript environment, you can install the `ggsql-wasm` package from [npm](https://www.npmjs.com/package/ggsql-wasm):
+
+```bash
+npm install ggsql-wasm
+```
+
+:::

doc/assets/logos/webassembly.svg

@@ -0,0 +1,2 @@
+sidebar: get_started
+page-navigation: true

doc/get_started/installation.qmd

@@ -0,0 +1,87 @@
+---
+title: Command line interface
+---
+
+The `ggsql` command line interface lets you execute queries and validate syntax directly from the terminal. While it may not be the most ergonomic way to interact directly with ggsql, it is useful for scripting, automation, and building tools around ggsql.
+
+## Installation
+
+Install the ggsql CLI on your system using the standard [installation instructions](../installation.html).
+
+## Executing a query
+
+You can execute a ggsql query from a string with `ggsql exec`:
+
+```bash
+ggsql exec "VISUALISE species AS fill FROM ggsql:penguins DRAW bar"
+```
+
+Or run a `.gsql` file:
+
+```bash
+ggsql run my_query.gsql
+```
+
+In both cases, output is written to `stdout` as a Vega-Lite JSON spec. You can redirect it to a file:
+
+```bash
+ggsql run my_query.gsql > chart.vl.json
+```
+
+Such files can be rendered as images using tools that work with Vega-Lite specs, such the [Online Vega Editor](https://vega.github.io/editor/) or [vl-convert](https://github.com/vega/vl-convert) command line tool. For example,
+
+```bash
+vl-convert vl2png -i chart.vl.json -o chart.png
+```
+
+A standard SQL query can also be provided to ggsql. If the query returns a table, the resulting values will be written to `stdout`.
+
+## Validating a query
+
+If you only want to check that a query is syntactically valid without executing it, use `ggsql validate`:
+
+```bash
+$ ggsql validate "VISUALISE x, y FROM table DRAW point"
+✓ Query syntax is valid
+```
+
+## Database connections
+
+Both `ggsql exec` and `ggsql run` accept a `--reader` flag that can be used to specify a connection string to be used when executing the query. If not provided, ggsql will use an empty in-memory duckdb connection, equivalent to `--reader duckdb://memory`.
+
+```bash
+$ ggsql exec --reader sqlite://sample/ggsql_test.sqlite \
+  "SELECT * FROM test_table LIMIT 3"
+col_a,  col_b, col_c
+215.87, 75.11, delta
+418.78, 71.75, delta
+495.75, 12.55, delta
+
+$ ggsql exec --reader odbc://DSN=ggsql-pg-test \
+  "SELECT * FROM test_table LIMIT 3"
+col_a,  col_b, col_c
+319.34, 91.45, gamma
+299.08, 49.36, epsilon
+12.5,   29.48, gamma
+```
+
+## Documentation
+
+The ggsql CLI has built-in documentation for ggsql syntax and usage. Run `ggsql docs` for an overview of available documentation topics, and `ggsql docs [topic]` to read about a specific topic.
+
+```bash
+$ ggsql docs draw
+DRAW is perhaps the most important clause in ggsql as it defines a layer in your 
+visualisation. A layer is a single instance of a visual representation of a dataset.
+[...]
+```
+
+A ggsql skill, a usage guide intended for AI assistants and humans, can also be output using the `ggsql skill` command.
+
+```bash
+$ ggsql skill
+                          ggsql Query Writer
+ggsql is a SQL extension for declarative data visualization based on
+Grammar of Graphics principles.
+[...]
+```

doc/get_started/tooling.qmd

@@ -0,0 +1,17 @@
+---
+title: Tooling
+---
+
+Now that we understand some of the most important parts of the syntax let's spend a bit of time on where and how to apply it. All the examples on this website are interactive and run directly in the browser, which is obviously useful for teaching, but it will not suffice for your day-to-day work where you need to interact with your own data. ggsql is a general tool you can use in a multitude of ways and we'll go over them in this section.
+
+- **[Positron / VS Code](positron-vscode.qmd)** --- Full language support in your IDE with syntax highlighting, autocomplete, and an integrated REPL.
+
+- **[Jupyter & Quarto](jupyter-quarto.qmd)** --- Use ggsql as a kernel in Jupyter or Quarto for interactive data exploration and reproducible documents.
+
+- **[CLI](cli.qmd)** --- Execute queries and validate syntax from the command line.
+
+- **[Python](python.qmd)** --- Use ggsql from Python.
+
+- **[R](r.qmd)** --- Use ggsql from R.
+
+- **[WebAssembly](webassembly.qmd)** --- Run ggsql entirely in the browser with no installation.

doc/get_started/tooling/_metadata.yml

@@ -0,0 +1,66 @@
+---
+title: Jupyter & Quarto
+---
+
+Once the ggsql Jupyter kernel has been installed you can use ggsql in Jupyter notebooks and Quarto documents.
+
+## Installation
+
+First, install ggsql on your system using the Jupyter kernel [installation instructions](../installation.html). If you do not already have Jupyter installed, you should install it in a new virtual environment using [uv](https://docs.astral.sh/uv/) or `pip` first:
+
+```bash
+uv venv
+uv pip install jupyter
+uv pip install ggsql-jupyter
+source .venv/bin/activate
+ggsql-jupyter --install
+```
+
+To verify installation, run `jupyter kernelspec list` and check that `ggsql` is listed as an available kernel.
+
+```bash
+$ jupyter kernelspec list
+Available kernels:
+  python3    /tmp/.venv/share/jupyter/kernels/python3
+  ggsql      /home/user/.local/share/jupyter/kernels/ggsql
+```
+
+You can now use ggsql in your Quarto documents or Jupyter notebooks.
+
+## Quarto documents
+
+For a Quarto document, use the `ggsql` language name in a code block to tell the renderer to use the ggsql kernel:
+
+````markdown
+```{{ggsql}}
+VISUALISE species AS fill
+FROM ggsql:penguins
+DRAW bar
+```
+````
+
+Each block in the document shares the same session, so tables created in one block will be available in subsequent blocks.
+
+![](./screenshots/quarto-document.png)
+
+## Jupyter notebooks
+
+First, start a Jupyter notebook server in your terminal:
+
+```bash
+jupyter notebook
+```
+
+When creating a new notebook, select the ggsql kernel from the kernel selector. Each cell in the notebook can contain a ggsql query, and the resulting visualisation will be displayed inline below the cell.
+
+As with Quarto, each cell in the notebook uses the same session, so tables created in one cell will be available in subsequent cells.
+
+![](./screenshots/jupyter-notebook.png)
+
+## Database connections
+
+By default, the ggsql kernel starts with an empty in-memory duckdb database connection. A "magic" comment can be used to initiate a different database connection after the session has launched, which can be either a comment in your Quarto code block or invoked directly in a Jupyter notebook cell.
+
+The connection syntax is `-- @connect: [connection_uri]`, where `[connection_uri]` is a ggsql database connection string in the same format as accepted by the [ggsql CLI](cli.html).
+
+![](./screenshots/jupyter-connections.png)