docs: update guide and styles (#117)

raystack · Feb 21, 2022 · 7eee523 · 7eee523
1 parent 004376f
commit 7eee523
Show file tree

Hide file tree

Showing 28 changed files with 2,074 additions and 29,563 deletions.
diff --git a/.gitignore b/.gitignore
@@ -23,3 +23,4 @@ vendor/
 .env
 stencil
 /config.yaml
+node_modules
diff --git a/README.md b/README.md
@@ -55,15 +55,15 @@ $ stencil version
 
 Stencil has three major components. Server, CLI and clients. Stencil server and CLI are bundled in a single binary.
 
-### Server
+**Server**
 
 Stencil server provides a way to store and fetch schemas and enforce compatability rules. Run `stencil server --help` to see instructions to manage Stencil server.
 
-### CLI
+**CLI**
 
 Stencil CLI allows users to iteract with server to create, view, and search schemas. CLI is fully featured but simple to use, even for those who have very limited experience working from the command line. Run `stencil --help` to see list of all available commands and instructions to use.
 
-## Clients
+**Clients**
 
 Stencil clients allows application to interact with stencil server to eserialize and deserialize messages using schema. Stencil supports clients in multiple languages.
 

diff --git a/docs/docs/formats/avro.md b/docs/docs/formats/avro.md
@@ -0,0 +1,3 @@
+# Avro
+
+We are in the process of actively improving Stencil documentation. This guide will be updated very soon.
diff --git a/docs/docs/formats/json.md b/docs/docs/formats/json.md
@@ -0,0 +1,3 @@
+# JSON
+
+We are in the process of actively improving Stencil documentation. This guide will be updated very soon.
diff --git a/docs/docs/formats/protobuf.md b/docs/docs/formats/protobuf.md
@@ -0,0 +1,3 @@
+# Protobuf
+
+We are in the process of actively improving Stencil documentation. This guide will be updated very soon.
diff --git a/docs/docs/concepts.md → docs/docs/glossary.md b/docs/docs/concepts.md → docs/docs/glossary.md
@@ -1,4 +1,4 @@
-# Concepts
+# Glossary
 
 This section describes the core elements of a schema registry.
 

diff --git a/docs/docs/guides/0_introduction.md b/docs/docs/guides/0_introduction.md
@@ -0,0 +1,36 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Introduction
+
+This tour introduces you to Stencil schema registry. Along the way you will learn how to manage schemas, enforce rules, serialise and deserialise data using stencil clients.
+
+### Prerequisites
+
+This tour requires you to have Stencil CLI tool installed on your local machine. You can run `stencil version` to verify the installation. Please follow installation guide if you do not have it installed already.
+
+Stencil CLI and clients talks to Stencil server to publish and fetch schema. Please make sure you also have a stencil server running. You can also run server locally with `stencil server start` command. For more details check deployment guide.
+
+### Help
+
+At any time you can run the following commands.
+
+```bash
+# Check the installed version for stencil cli tool
+$ stencil version
+
+# See the help for a command
+$ stencil --help
+```
+
+Help command can also be run on any sub command.
+
+```bash
+$ stencil schema --help
+```
+
+Check the reference for stencil cli commands.
+
+```bash
+$ stencil reference
+```
diff --git a/docs/docs/guides/1_quickstart.md b/docs/docs/guides/1_quickstart.md
@@ -0,0 +1,199 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Quickstart
+
+This quick start will explore how to use Stencil command line interface and client libraries inside your application code. As part of this quick start we will start stencil server, create schema and then use stencil clients to serialise and deserialise data using registered schemas.
+
+## Prerequisites
+
+- [Docker](installation#using-docker-image) or a [local installation](installation#binary-cross-platform) of the Stencil binary.
+- A development environment applicable to one of the languages in this quick start (currently Go, Java, and JavaScript).
+- Postgres database and [protoc](https://github.com/protocolbuffers/protobuf#protocol-compiler-installation) if your schema format is protobuf.
+
+## Step 1: Start server
+
+<Tabs>
+<TabItem value="executable" label="Executable" default>
+
+Run stencil server locally using installed stencil binary.
+Note: Below command assumes `stencil_dev` db present in your postgres instance.
+
+```bash
+$ export DB_CONNECTIONSTRING=postgres://postgres@localhost:5432/stencil_dev?sslmode=disable
+
+# Run database migrations
+$ stencil server migrate
+
+# Stencil server
+$ stencil server start
+
+# Check if server running
+$ curl -X GET http://localhost:8080/ping
+```
+
+</TabItem>
+<TabItem value="docker" label="Docker">
+
+Run stencil server locally using docker
+Note: Below command assumes `stencil_dev` db present in your postgres instance.
+
+```bash
+# Run database migrations
+$ docker run -e PORT=8000 -e DB_CONNECTIONSTRING=postgres://postgres@host.docker.internal:5432/stencil_dev?sslmode=disable -p 8000:8000 odpf/stencil server migrate
+
+# Stencil server at port 8000
+$ docker run -e PORT=8000 -e DB_CONNECTIONSTRING=postgres://postgres@host.docker.internal:5432/stencil_dev?sslmode=disable -p 8000:8000 odpf/stencil server start
+
+# Check if server running
+$ curl -X GET http://localhost:8000/ping
+```
+
+</TabItem>
+</Tabs>
+
+## Step 2: Create schema
+
+<Tabs>
+<TabItem value="protobuf" label="Protobuf">
+
+```bash
+$ mkdir example
+$ cd example
+
+# Create a sample proto schema.
+$ echo "syntax=\"proto3\";
+  package stencil;
+  message One {
+    int32 field_one = 1;
+  }" > schema.proto
+
+# Create proto descriptor file
+$ protoc --descriptor_set_out=./schema.desc --include_imports ./**/*.proto
+```
+
+</TabItem>
+<TabItem value="avro" label="Avro">
+
+```bash
+$ mkdir example
+$ cd example
+
+# Create a sample avro schema.
+$ echo "{
+   \"type\" : \"record\",
+   \"namespace\" : \"Tutorialspoint\",
+   \"name\" : \"Employee\",
+   \"fields\" : [
+      { \"name\" : \"Name\" , \"type\" : \"string\" },
+      { \"name\" : \"Age\" , \"type\" : \"int\" }
+   ]
+}" > schema.json
+
+```
+
+</TabItem>
+<TabItem value="json" label="JSON">
+
+```bash
+$ mkdir example
+$ cd example
+
+# Create example JSON schema file.
+$ echo "{
+  \"type\":\"object\",
+  \"properties\":{
+    \"f1\":{
+      \"type\":\"string\"
+      }
+    },
+  \"additionalProperties\": false
+}" > schema.json
+
+```
+
+</TabItem>
+</Tabs>
+
+## Step 3: Upload to server
+
+<Tabs>
+<TabItem value="cli" label="CLI">
+
+```bash
+# Create namespace named "quickstart" with backward compatibility enabled
+$ stencil namespace create -c COMPATIBILITY_BACKWARD -f FORMAT_PROTOBUF -d "For quickstart guide" --host http://localhost:8000
+
+# List namespaces
+$ stencil namespace list
+
+# Upload generated schema proto descriptor file to server with schema name as `example` under `quickstart` namespace.
+$ stencil schema create example --namespace=quickstart –-filePath=schema.desc
+
+# Get list of schemas available in a namespace
+$ stencil schema list --host http://localhost:8000
+
+# Get list of versions available for particular schema. These versions are auto generated.
+# Version numbers managed by stencil.
+$ stencil schema version example -n quickstart  --host http://localhost:8000
+
+# Download specific version of particular schema
+$ stencil schema get example --version 1 --host http://localhost:8000
+
+# Download latest version of particular schema
+$ stencil schema get example  -n quickstart --host http://localhost:8000
+```
+
+</TabItem>
+<TabItem value="api" label="API">
+
+```bash
+# Create namespace named "quickstart" with backward compatibility enabled
+$ curl -X POST http://localhost:8000/v1beta1/namespaces -H 'Content-Type: application/json' -d '{"id": "quickstart", "format": "FORMAT_PROTOBUF", "compatibility": "COMPATIBILITY_BACKWARD", "description": "For quickstart guide"}'
+
+# List namespaces
+$ curl http://localhost:8000/v1beta1/namespaces
+
+# Upload generated schema proto descriptor file to server with schema name as `example` under `quickstart` namespace.
+$ curl -X POST http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example --data-binary "@schema.desc"
+
+# Get list of schemas available in a namespace
+$ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas
+
+# Get list of versions available for particular schema. These versions are auto generated.
+# Version numbers managed by stencil.
+$ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example/versions
+
+# Download specific version of particular schema
+$ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example/versions/1
+
+# Download latest version of particular schema
+$ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example;
+```
+
+</TabItem>
+</Tabs>
+
+## Step 4: Using client
+
+Let's use this API in our GO client
+
+```go
+package main
+
+import (
+       "log"
+       stencil "github.com/odpf/stencil/clients/go"
+)
+
+func main() {
+    url := "http://localhost:8000/v1/namespaces/quickstart/descriptors/example/versions/latest"
+    client, err := stencil.NewClient([]string{url}, stencil.Options{})
+    if err != nil {
+      log.Fatal("Unable to create client", err)
+      return
+    }
+    desc, err := client.GetDescriptor("stencil.One")
+    // ...
+}
+```
diff --git a/docs/docs/guides/2_manage_namespace.md b/docs/docs/guides/2_manage_namespace.md
@@ -0,0 +1,3 @@
+# Manage namespaces
+
+We are in the process of actively improving Stencil documentation. This guide will be updated very soon.
diff --git a/docs/docs/guides/quick_start.md → docs/docs/guides/3_manage_schemas.md b/docs/docs/guides/quick_start.md → docs/docs/guides/3_manage_schemas.md
@@ -1,36 +1,6 @@
-# Quick start guide
+# Manage schemas
 
-In this guide we're going to create a example proto file descriptorset then setup local stencil server with local file system as backend, then try out server APIs then we move on to using these APIs in Stencil GO client.
-
-This guide assumes you already have [docker](https://www.docker.com/), `postgres` and [protoc](https://github.com/protocolbuffers/protobuf#protocol-compiler-installation) installed on your system.
-
-## Create proto descriptorset file
-
-```bash
-$ mkdir example
-$ cd example
-# create example proto file. You can add as many proto files as you want.
-$ echo "syntax=\"proto3\";\npackage stencil;\nmessage One {\n  int32 field_one = 1;\n}" > one.proto
-
-# create descriptor file
-$ protoc --descriptor_set_out=./file.desc --include_imports ./**/*.proto
-```
-
-## Run stencil server locally using docker with local filesystem as backend store
-
-Note: Below command assumes `stencil_dev` db present in your postgres instance.
-
-```bash
-# To run migrations
-$ docker run -e PORT=8000 -e DB_CONNECTIONSTRING=postgres://postgres@host.docker.internal:5432/stencil_dev?sslmode=disable -p 8000:8000 odpf/stencil server migrate
-# This will run stencil server at port 8000
-$ docker run -e PORT=8000 -e DB_CONNECTIONSTRING=postgres://postgres@host.docker.internal:5432/stencil_dev?sslmode=disable -p 8000:8000 odpf/stencil server start
-
-# check if server running
-$ curl -X GET http://localhost:8000/ping
-```
-
-## Try Stencil server APIs
+## Create a schema
 
 ```bash
 # create namespace named "quickstart" with backward compatibility enabled
@@ -41,10 +11,18 @@ curl http://localhost:8000/v1beta1/namespaces
 
 # upload generated proto descriptor file to server with schema name as `example` under `quickstart` namespace.
 curl -X POST http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example --data-binary "@file.desc"
+```
 
+## List schema
+
+```bash
 # get list of schemas available in a namespace
 curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas
+```
+
+## View schema
 
+```bash
 # get list of versions available for particular schema. These versions are auto generated. Version numbers managed by stencil.
 curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example/versions
 
@@ -53,7 +31,11 @@ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example/
 
 # download latest version of particular schema
 curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example;
+```
+
+## Update schema
 
+```bash
 # now let's try uploading breaking proto definition. Note that proto field number has changed from 1 to 2.
 echo "syntax=\"proto3\";\npackage stencil;\nmessage One {\n  int32 field_one = 2;\n}" > one.proto;
 
@@ -71,32 +53,15 @@ protoc --descriptor_set_out=./file.desc --include_imports ./**/*.proto
 
 # now try to upload this descriptor file with same name as before. This call should succeed
 curl -X POST http://localhost:8000/v1/namespaces/quickstart/schemas --data-binary "@file.desc"
+```
+
+## List versions
+
+```bash
 
 # now try versions api. It should have 2 versions now.
 curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example/versions
 
 # upload schema can be called multiple times. Stencil server will retain old version if it's already uploaded. This call won't create new version again. You can verify by using versions API again.
 curl -X POST http://localhost:8000/v1/namespaces/quickstart/schemas --data-binary "@file.desc"
 ```
-
-## Let's use this API in our GO client
-
-```go
-package main
-
-import (
-       "log"
-       stencil "github.com/odpf/stencil/clients/go"
-)
-
-func main() {
-    url := "http://localhost:8000/v1/namespaces/quickstart/descriptors/example/versions/latest"
-    client, err := stencil.NewClient([]string{url}, stencil.Options{})
-    if err != nil {
-      log.Fatal("Unable to create client", err)
-      return
-    }
-    desc, err := client.GetDescriptor("stencil.One")
-    // ...
-}
-```
diff --git a/docs/docs/guides/4_clients.md b/docs/docs/guides/4_clients.md
@@ -0,0 +1 @@
+# Using clients