Create a book for documentation

Adds a book written in mdbook format which contains documentation
samuelorji · Apr 5, 2021 · 42f63ea · 42f63ea
1 parent 037012c
commit 42f63ea
Show file tree

Hide file tree

Showing 10 changed files with 155 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,4 @@
 /scylla/target
 /target
 Cargo.lock
+/book/book
diff --git a/book/book.toml b/book/book.toml
@@ -0,0 +1,14 @@
+[book]
+title = "Scylla Rust Driver"
+description = "Documentation for Scylla Rust Driver"
+authors = []
+language = "en"
+multilingual = false
+src = "src"
+
+[rust]
+edition = "2018"
+
+[output.html]
+default-theme = "ayu"
+git-repository-url = "https://github.com/scylladb/scylla-rust-driver"
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -0,0 +1,12 @@
+# Summary
+
+[Scylla Rust Driver](title-page.md)
+
+- [Quick start](quickstart/quickstart.md)
+    - [Creating a project](quickstart/create-project.md)
+    - [Running Scylla using Docker](quickstart/scylla-docker.md)
+    - [Connecting and running a simple query](quickstart/example.md)
+
+- [Connecting to the cluster](connecting/connecting.md)
+
+- [Making queries](queries/queries.md)
diff --git a/book/src/connecting/connecting.md b/book/src/connecting/connecting.md
diff --git a/book/src/queries/queries.md b/book/src/queries/queries.md
diff --git a/book/src/quickstart/create-project.md b/book/src/quickstart/create-project.md
@@ -0,0 +1,32 @@
+# Creating a project
+
+To create a new project run:
+```shell
+cargo new myproject
+```
+
+In `Cargo.toml` add required dependencies:
+```toml
+[dependencies]
+scylla = { git = "https://github.com/scylladb/scylla-rust-driver", branch = "main" }
+tokio = { version = "1.1.0", features = ["full"] }
+```
+> Note that when specifying a dependency as a git link, updates will not be automatically pulled.
+> Running `cargo update` will update the git dependency manually.
+
+In `main.rs` put:
+```rust
+# extern crate scylla;
+# extern crate tokio;
+use scylla::Session;
+
+#[tokio::main]
+async fn main() {
+    println!("Hello scylla!");
+}
+```
+
+Now running `cargo run` should print:
+```shell
+Hello scylla!
+```
diff --git a/book/src/quickstart/example.md b/book/src/quickstart/example.md
@@ -0,0 +1,52 @@
+# Connecting and running a simple query
+
+Now everything is ready to use the driver.
+Here is a small example:
+```rust
+# extern crate scylla;
+# extern crate tokio;
+use scylla::{IntoTypedRows, Session, SessionBuilder};
+use std::error::Error;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    // Create a new Session which connects to node at 127.0.0.1:9042
+    let session: Session = SessionBuilder::new()
+        .known_node("127.0.0.1:9042")
+        .build()
+        .await?;
+
+    // Create an example keyspace and table
+    session
+        .query(
+            "CREATE KEYSPACE IF NOT EXISTS ks WITH REPLICATION = \
+            {'class' : 'SimpleStrategy', 'replication_factor' : 1}",
+            &[],
+        )
+        .await?;
+
+    session
+        .query(
+            "CREATE TABLE IF NOT EXISTS ks.extab (a int primary key)",
+            &[],
+        )
+        .await?;
+
+    // Insert a value into the table
+    let to_insert: i32 = 12345;
+    session
+        .query("INSERT INTO ks.extab (a) VALUES(?)", (to_insert,))
+        .await?;
+
+    // Query rows from the table and print them
+    if let Some(rows) = session.query("SELECT a FROM ks.extab", &[]).await?.rows {
+        // Parse each row as a tuple containing single i32
+        for row in rows.into_typed::<(i32,)>() {
+            let read_row: (i32,) = row?;
+            println!("Read a value from row: {}", read_row.0);
+        }
+    }
+
+    Ok(())
+}
+```
diff --git a/book/src/quickstart/quickstart.md b/book/src/quickstart/quickstart.md
@@ -0,0 +1,3 @@
+# Quick Start
+
+In this chapter we will set up a Rust project and run a few simple queries.
diff --git a/book/src/quickstart/scylla-docker.md b/book/src/quickstart/scylla-docker.md
@@ -0,0 +1,25 @@
+# Running Scylla using Docker
+
+To make queries we will need a running Scylla instance. The easiest way is to use a [Docker](https://www.docker.com/) image.  
+Please [install Docker](https://docs.docker.com/engine/install) if it's not installed.
+
+### Linux:
+To start Scylla run:
+```shell
+sudo docker run --rm -it -p 9042:9042 scylladb/scylla --smp 2
+```
+
+Docker will download the image, then after minute or two there should be a message like:
+```shell
+Starting listening for CQL clients on 172.17.0.2:9042
+```
+This means that Scylla is ready to receive queries
+
+To stop this instance press `Ctrl + C`
+
+### Windows
+TODO
+
+### More information
+More information about this image can be found on [dockerhub](https://hub.docker.com/r/scylladb/scylla)
+
diff --git a/book/src/title-page.md b/book/src/title-page.md
@@ -0,0 +1,16 @@
+# Scylla Rust Driver
+This book contains documentation for [scylla-rust-driver](https://github.com/scylladb/scylla-rust-driver) - a driver
+for the [Scylla](https://scylladb.com) database written in Rust. 
+Although optimized for Scylla, the driver is also compatible with [Apache Cassandra®](https://cassandra.apache.org/).
+
+### Other documentation
+* [Examples](https://github.com/scylladb/scylla-rust-driver/tree/main/examples)
+*  *API documentation* (Coming soon, for now download the [repo](https://github.com/scylladb/scylla-rust-driver) and run `cargo doc`)
+* [Scylla documentation](https://docs.scylladb.com)
+* [Cassandra® documentation](https://cassandra.apache.org/doc/latest/)
+
+
+## Contents
+* [Quick start](quickstart/quickstart.md) - Setting up a Rust project using `scylla-rust-driver` and running a few queries
+* [Connecting to the cluster](connecting/connecting.md) - Configuring a connection to scylla cluster
+* [Making queries](queries/queries.md) - Making different types of queries (simple, prepared, batch, paged)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Quick Start

		In this chapter we will set up a Rust project and run a few simple queries.