put tutorials on mkdocs

docs/index.md

@@ -1,4 +1,4 @@
-# Zoe - The Kafka companion
+# Zoe - The Kafka Companion
 
 Zoe is a command line tool to interact with kafka in an easy and intuitive way. Wanna see this in action ? check out this demo...
 
@@ -10,7 +10,7 @@ Zoe really shines when it comes to interacting with cloud hosted kafka clusters
 
 Here are some of the most interesting features of zoe :
 
-- Supports offloading consumption of data to lambda functions, kubernetes pods, etc. for parallelism (ex. adding `-r kubernetes` would offload all the requests to multiple pods in a configured kubernetes cluster).
+- Supports [offloading consumption of data](advanced/runners/overview.md) to lambda functions, kubernetes pods, etc. for parallelism (ex. adding `-r kubernetes` would offload all the requests to multiple pods in a configured kubernetes cluster).
 - Consume kafka topics from a specific point in time (ex. using `--from 'PT5h` from the last 5 hours).
 - Filter data based on content (ex. using `--filter "id == '12345'"` filters records with the selected id).
 - Monitor consumer groups' offsets.

docs/tutorials/avro.md

@@ -0,0 +1,70 @@
+# Zoe with Avro
+
+This tutorial shows zoe support for avro and the schema registry. If you are new to zoe, start with [the simple example](../tutorials/simple.md).
+
+## What you will learn
+
+In this tutorial, you will learn the following aspects of zoe :
+
+- listing avro schemas registered in the schema registry
+- deploying `.avdl` avro schemas
+- writing json data into kafka topics using avro
+- reading avro data from a topic
+- using jmespath expressions to filter read data based on its content.
+
+## Prerequisites
+For this tutorial you will need :
+
+- Zoe
+- Docker and docker-compose
+
+## Prepare the environment
+
+- Clone the [repository](https://github.com/adevinta/zoe) : `git clone https://github.com/adevinta/zoe.git`
+- Go to the directory : `tutorials/simple`
+- Spin up the kafka cluster : `docker-compose up -d`.
+- Point zoe to this tutorial's config : `export ZOE_CONFIG_DIR=$(pwd)/config`
+
+Now, you're ready to use zoe to interact with the local kafka cluster. This cluster is available in the provided config above under the `local` alias (take a look at `zoe-config/default.yml`)
+
+## Start using Zoe
+
+In this tutorial we are still using the cats facts data that we used in the previous tutorial. But this time we are serializing into kafka in avro format.
+
+In order to do this, we have provided a ready to use avro schema that describe the fact cats data in the `schema.avdl` file. The first step is to deploy this schema.
+
+Usually, to deploy an `.avdl` file into the schema registry we first need to compile it into an `.avsc` file before posting it to the registry. With zoe, this compilation step is done automatically for us. In fact, zoe handles `.avdl` files seamlessly.
+
+```
+# list currently registered avro schemas
+zoe -q -c local schemas list
+
+# deploy the cat facts schema from the 
+zoe -q -c local schemas deploy \
+  --avdl \
+  --from-file schema.avdl \
+  --name CatFact \
+  --strategy topicRecord \
+  --topic input \
+  --dry-run
+```
+
+Produce some events from the `data.json` using avro :
+```
+zoe -c local topics produce --topic input --from-file $(pwd)/data.json
+``` 
+
+Read the data from the topic :
+```
+# read the 10 last events
+zoe -q -o table -c local topics consume input -n 10 --from 'PT1h'
+
+# display events in a table
+zoe -q -o table -c local topics consume input -n 10 --from 'PT1h' \
+       --query '{id: _id, type: type, user: user, upvotes: upvotes}'
+
+# filter out Kasimir's data
+zoe -q -o table -c local topics consume input -n 10 --from 'PT1h' \
+       --query '{id: _id, type: type, user: user, upvotes: upvotes}' \
+       --filter "user.name.first == 'Kasimir'"
+```

docs/tutorials/overview.md

@@ -0,0 +1,7 @@
+# Tutorials
+
+The zoe repository provides a bunch of Hands-on tutorials that walks you through the most useful concepts of zoe. These tutorials are self contained and do not require extra infrastructure other than you own machine.
+
+- [A simple example](simple.md) : This tutorial walks you through the most basic functionalities of zoe. It makes use of a dataset downloaded from the [Cat Facts API](http://www.catfact.info/) to explore reading and writing data from / into kafka using zoe.
+- [Zoe with Avro](avro.md) : This tutorial shows zoe support for avro and the schema registry. If you are new to zoe, start with the simple example above.
+- [Zoe with Kubernetes](kubernetes.md) : This tutorial shows you how you can offload consumption and interactions to kubernetes pods for parallelism.

docs/tutorials/simple.md

@@ -0,0 +1,72 @@
+# A simple example
+
+This tutorial walks you through the most basic functionalities of zoe. It makes use of a dataset downloaded from the [Cat Facts API](http://www.catfact.info/) to explore reading and writing data from / into kafka using zoe.
+
+In this tutorial, we will spin up a simple one node kafka cluster and then interact with it using zoe.
+
+If you want to run this tutorial yourself, you can find all the relevant files / datasets [here](https://github.com/adevinta/zoe/tree/master/tutorials/simple).
+
+## What you will learn
+
+In this tutorial, you will learn the following aspects of zoe :
+
+- listing topics
+- describing topics
+- writing json data into kafka topics
+- reading json data from a topic
+- using jmespath expressions to filter read data based on its content.
+
+## Prerequisites
+
+For this tutorial you will need :
+
+- Zoe (follow instructions [here](../install/overview.md))
+- Docker and docker-compose
+
+## Prepare the environment
+
+- Clone the [repository](https://github.com/adevinta/zoe) : `git clone https://github.com/adevinta/zoe.git`
+- Go to the directory : `tutorials/simple`
+- Spin up the kafka cluster : `docker-compose up -d`.
+- Point zoe to this tutorial's config : `export ZOE_CONFIG_DIR=$(pwd)/config`
+
+Now, you're ready to use zoe to interact with the local kafka cluster. This cluster is available in the provided config above under the `local` alias. Do not hesitate to take a look at the configuration file at `config/default.yml` to have a first sight on how zoe is configured.
+
+## Start using Zoe
+
+To list and describe topics :
+
+```
+# interact with the topics
+zoe -c local topics list
+zoe -c local topics describe input-events-topic
+```
+
+To avoid repeating the `-c local` option on each command you can set the `local` cluster as the default one for the current session : `export ZOE_CLUSTER=local`. Now you can write :
+
+```
+# interact with the topics
+zoe topics list
+``` 
+
+Let's write some data in the topic. We have some cats facts in the `data.json` file that we can use. The following command writes this json data into the `input-events-topic` aliased as the `input` in zoe's configuration (`config/default.yml`) :
+
+```
+zoe topics produce --topic input --from-file $(pwd)/data.json
+``` 
+
+Read the data that we have just inserted :
+
+```
+# read the 10 last events
+zoe -q -o table topics consume input -n 10 --from 'PT1h'
+
+# display events in a table
+zoe -q -o table topics consume input -n 10 --from 'PT1h' \
+       --query '{id: _id, type: type, user: user, upvotes: upvotes}'
+
+# filter out Kasimir's data
+zoe -q -o table topics consume input -n 10 --from 'PT1h' \
+       --query '{id: _id, type: type, user: user, upvotes: upvotes}' \
+       --filter "user.name.first == 'Kasimir'"
+```

mkdocs.yml

@@ -48,4 +48,8 @@ nav:
           - 'Local': advanced/runners/local.md
           - 'Lambda': advanced/runners/lambda.md
           - 'Kubernetes': advanced/runners/kubernetes.md
-  - 'Tutorials': tutorials.md
+  - 'Tutorials':
+      - 'Overview': tutorials/overview.md
+      - 'Simple': tutorials/simple.md
+      - 'Zoe with Avro': tutorials/avro.md
+      - 'Zoe with Kubernetes': tutorials/kubernetes.md

tutorials/avro/README.md

@@ -1,70 +1,3 @@
 # Zoe with Avro
 
-This tutorial shows zoe support for avro and the schema registry. If you are new to zoe, start with [the simple example](../../tutorials/simple/simple.md).
-
-## What you will learn
-
-In this tutorial, you will learn the following aspects of zoe :
-
-- listing avro schemas registerd in the schema registry
-- deploying `.avdl` avro schemas
-- writing json data into kafka topics using avro
-- reading avro data from a topic
-- using jmespath expressions to filter read data based on its content.
-
-## Prerequisites
-For this tutorial you will need :
-
-- Zoe
-- Docker and docker-compose
-
-## Prepare the environment
-
-- Clone the [repository](https://github.com/adevinta/zoe) : `git clone https://github.com/adevinta/zoe.git`
-- Go to the directory : `tutorials/simple`
-- Spin up the kafka cluster : `docker-compose up -d`.
-- Point zoe to this tutorial's config : `export ZOE_CONFIG_DIR=$(pwd)/config`
-
-Now, you're ready to use zoe to interact with the local kafka cluster. This cluster is available in the provided config above under the `local` alias (take a look at `zoe-config/default.yml`)
-
-## Start using Zoe
-
-In this tutorial we are still using the cats facts data that we used in the previous tutorial. But this time we are serializing into kafka in avro format.
-
-In order to do this, we have provided a ready to use avro schema that describe the fact cats data in the `schema.avdl` file. The first step is to deploy this schema.
-
-Usually, to deploy an `.avdl` file into the schema registry we first need to compile it into an `.avsc` file before posting it to the registry. With zoe, this compilation step is done automatically for us. In fact, zoe handles `.avdl` files seamlessly.
-
-```
-# list currently registered avro schemas
-zoe -q -c local schemas list
-
-# deploy the cat facts schema from the 
-zoe -q -c local schemas deploy \
-  --avdl \
-  --from-file schema.avdl \
-  --name CatFact \
-  --strategy topicRecord \
-  --topic input \
-  --dry-run
-```
-
-Produce some events from the `data.json` using avro :
-```
-zoe -c local topics produce --topic input --from-file $(pwd)/data.json
-``` 
-
-Read the data from the topic :
-```
-# read the 10 last events
-zoe -q -o table -c local topics consume input -n 10 --from 'PT1h'
-
-# display events in a table
-zoe -q -o table -c local topics consume input -n 10 --from 'PT1h' \
-       --query '{id: _id, type: type, user: user, upvotes: upvotes}'
-
-# filter out Kasimir's data
-zoe -q -o table -c local topics consume input -n 10 --from 'PT1h' \
-       --query '{id: _id, type: type, user: user, upvotes: upvotes}' \
-       --filter "user.name.first == 'Kasimir'"
-```
+This tutorial can be [here](https://adevinta.github.io/zoe/tutorials/avro).