Improved documentation

.gitignore

@@ -1 +1,2 @@
 examples/rust/target/**/*
+**/.env

README.md

@@ -3,9 +3,17 @@
 This repository contains protobufs (protocol buffers) for clients of Sift to interact directly with our gRPC service. If certain protobufs are not yet available for a particular API, please refer to the documentation for our
 [REST API](https://docs.siftstack.com/api-docs/rest) which may expose those services via gRPC gateway.
 
-For manual installation instructions and usage examples for various languages please refer to the [examples](examples/) directory. If there aren't instructions for your particular programming language consider one of the following options:
+For manual installation instructions for a particular programming language, click on one of the following links:
+- [Go](/docs/go.md)
+- [Rust](/docs/rust.md)
+
+Please keep in mind that the manual installation instructions aims to be general, and users are encouraged to modify any of the steps that best suits the needs of their project. The instructions do not need to be strictly followed.
+
+For usage examples you may also refer to the [examples](examples/) directory which demonstrates basic usage of the code generated from compiling the protobufs.
+
+If there aren't instructions for your particular programming language consider one of the following options:
 - Request for the Sift team to include instructions for your language of choice. Keep in mind that there are varying degrees of support for each language throughout the protobuf ecosystem. Depending on the language, support might be totally unavailable.
 - Compile the protobufs manually.
 - Use our [REST API](https://docs.siftstack.com/api-docs/rest).
 
-In the near future we will provide more installation options.
+In the near future we will plan to provide more installation options.

docs/go.md

@@ -0,0 +1,94 @@
+# Sift Protobuf Installation for Go
+
+Before proceeding with installation, you will need to ensure that you have the [buf CLI](https://buf.build/docs/installation) installed.
+
+If `$ which buf` generates a path to the executable, you may proceed to the installation steps.
+
+To install Sift protobufs in your project:
+
+1. Clone this repository onto your local machine and `cd` into it:
+
+```bash
+$ git clone https://github.com/sift-stack/sift
+$ cd sift
+```
+
+2. Assuming the path to the root of your Go project is `$PROJECT_DIR`, run the following command in the `sift` directory that you just cloned:
+
+```bash
+$ buf export protos --output=$PROJECT_DIR/protos --config protos/buf.yaml
+```
+
+The Sift protos can and its imports can now be found in your `$PROJECT_DIR/protos` directory.
+
+3. Copy the `buf` template for Go to your project directory:
+
+```bash
+$ cp buf_templates/buf.gen.go.yaml $PROJECT_DIR/buf.gen.yaml
+```
+
+4. `cd` into your Go project at `$PROJECT_DIR`.
+
+5. Once inside of your Go project, you'll need to modify the `managed.enabled.go_package_prefix.default` value of your `buf.gen.yaml` file to
+have the package prefix named after your Go module. If our Go module's name, for example, is `github.com/example_project`, then change the `buf.gen.yaml` to `github.com/example_project/gen/protos/go`. Your
+`buf.gen.yaml` should now look like the following:
+
+```yaml
+version: v1
+managed:
+  enabled: true
+  go_package_prefix:
+    default: "github.com/example_project/gen/protos/go"
+plugins:
+  - plugin: buf.build/protocolbuffers/go:v1.28.1
+    out: gen/protos/go
+    opt: paths=source_relative
+  - plugin: go-vtproto
+    out: gen/protos/go
+    opt: paths=source_relative
+  - plugin: buf.build/grpc-ecosystem/gateway:v2.16.2
+    out: gen/protos/go
+    opt: paths=source_relative
+```
+
+Refer to your `go.mod` file for the name of your Go module.
+
+6. Inside of the root of your project directory you may now compile your protobufs:
+
+```bash
+$ buf generate protos
+```
+
+Your project up to this point should look like the following (full depth not shown):
+
+```
+ example_project
+ ├─ buf.gen.yaml
+ ├─ gen
+ │  └─ protos
+ │     └─ go
+ ├─ go.sum
+ ├─ go.mod
+ └─ protos
+    ├─ protoc-gen-openapiv2
+    │  └─ options
+    ├─ google
+    │  └─ api
+    └─ sift
+       ├─ runs
+       ├─ notifications
+       ├─ annotations
+       ├─ users
+       ├─ common
+       ├─ assets
+       ├─ tags
+       └─ annotation_logs
+```
+
+7. Install any dependencies you might be missing that the generated code requires:
+
+```bash
+$ go get -d ./...
+```
+
+8. Now your project should be ready to use the generated Go code to interact with Sift's gRPC API. Please refer to the [example code](/examples/go) for usage.

docs/rust.md

@@ -0,0 +1,106 @@
+# Sift Protobuf Installation for Rust
+
+Before proceeding with installation, you will need to ensure that you have the [buf CLI](https://buf.build/docs/installation) installed.
+
+If `$ which buf` generates a path to the executable, you may proceed to the installation steps.
+
+To install Sift protobufs in your project:
+
+1. Clone this repository onto your local machine and `cd` into it:
+
+```bash
+$ git clone https://github.com/sift-stack/sift
+$ cd sift
+```
+
+2. Assuming the path to the root of your Rust project is `$PROJECT_DIR`, run the following command in the `sift` directory that you just cloned:
+
+```bash
+$ buf export protos --output=$PROJECT_DIR/protos --config protos/buf.yaml
+```
+
+The Sift protos can and its imports can now be found in your `$PROJECT_DIR/protos` directory.
+
+3. Copy the `buf` template for Rust to your project directory:
+
+```bash
+$ cp buf_templates/buf.gen.go.yaml $PROJECT_DIR/buf.gen.yaml
+```
+
+4. `cd` into your Rust project at `$PROJECT_DIR`.
+
+5. Once inside of your Rust project, declare a module called `gen` in your `main.rs` (unless you're crate is a lib-crate) and create a `src/gen/mod.rs` file.
+
+```rust
+// main.go
+
+/// Sift generated code
+mod gen;
+```
+
+Refer to the `buf.gen.yaml` in your project root if you need to modify the output path for the compiled protos.
+
+
+6. Inside of the root of your project directory you may now compile your protobufs:
+
+```bash
+$ buf generate protos
+```
+
+Your project up to this point should look like the following (full depth not shown):
+
+```
+ example_project
+ ├─ src
+ │  ├─ main.rs
+ │  └─ gen
+ │     ├─ sift.common.type.v1.rs
+ │     ├─ sift.runs.v2.rs
+ │     ├─ sift.annotation_logs.v1.rs
+ │     ├─ sift.runs.v2.tonic.rs
+ │     ├─ sift.users.v2.rs
+ │     ├─ mod.rs
+ │     ├─ sift.tags.v1.rs
+ │     ├─ sift.assets.v1.tonic.rs
+ │     ├─ sift.assets.v1.rs
+ │     ├─ sift.notifications.v1.tonic.rs
+ │     ├─ sift.users.v2.tonic.rs
+ │     ├─ sift.annotation_logs.v1.tonic.rs
+ │     ├─ grpc.gateway.protoc_gen_openapiv2.options.rs
+ │     ├─ sift.notifications.v1.rs
+ │     ├─ sift.annotations.v1.tonic.rs
+ │     ├─ google.api.rs
+ │     └─ sift.annotations.v1.rs
+ ├─ buf.gen.yaml
+ ├─ README.md
+ ├─ Cargo.lock
+ └─ Cargo.toml
+
+2 directories, 22 files
+```
+
+7. Ensure you have the following dependencies installed:
+
+```toml
+[package]
+name = "sift_cli"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+async-trait = "0.1.79"
+prost = "0.12.4"
+prost-types = "0.12.4"
+tonic = { version = "0.11.0", features = ["tls", "tls-roots", "tls-webpki-roots"] }
+```
+
+8. Declare the modules that will import the generated code in your `src/gen/mod.rs`. For example, we wish to use the generated `annotations` code for this example:
+
+```rust
+#[path = "sift.annotations.v1.rs"]
+pub mod annotations;
+```
+
+9. Now your project should be ready to use the generated Rust code to interact with Sift's gRPC API. Please refer to the [example code](/examples/rust/) for usage.

examples/README.md

@@ -1,15 +1,9 @@
 # Sift Protobufs Examples
 
-Currently there are recommended installation instructions and example usages for the following languages:
-- [Go](go/)
-- [Rust](rust/)
-
-Each example will cover how to manually compile the protobufs into the user's target language such that it's ready for immediate use in the user's project.
-Users are by no means obligated to follow these instructions exactly and are instead encouraged to do what makes the most sense for their project.
-
-In addition to covering installation the examples will also contain code that demonstrates how to use the compiled protobufs by building a basic CLI
-that allows users to query annotations by name via a case-insensitive partial substring match:
+This directory contains examples on how to use code generated from Sift protobufs for various programming languages.
 
+Each example is a small CLI that allows users to query annotations by doing a case-insensitive substring match against the name of each annotation which
+will behave like so:
 
 ```
 $ sift_cli voltage

examples/go/README.md

@@ -1,96 +1,22 @@
 # Sift Go Example
 
-Before proceeding with installation, you will need to ensure that you have the [buf CLI](https://buf.build/docs/installation) installed.
+To run this example ensure that you have Go and the [buf CLI](https://buf.build/docs/installation) installed.
 
-If `$ which buf` generates a path to the executable, you may proceed to the installation steps.
-
-To install Sift protobufs in your project:
-
-1. Clone this repository onto your local machine and `cd` into it:
-
-```bash
-$ git clone https://github.com/sift-stack/sift
-$ cd sift
-```
-
-2. Assuming the path to the root of your Go project is `$PROJECT_DIR`, run the following command in the `sift` directory that you just cloned:
-
-```bash
-$ buf export protos --output=$PROJECT_DIR/protos --config protos/buf.yaml
-```
-
-The Sift protos can and its imports can now be found in your `$PROJECT_DIR/protos` directory.
-
-3. Copy the `buf` template for Go to your project directory:
-
-```bash
-$ cp buf_templates/buf.gen.go.yaml $PROJECT_DIR/buf.gen.yaml
-```
-
-4. `cd` into your Go project at `$PROJECT_DIR`.
-
-5. Once inside of your Go project, you'll need to modify the `managed.enabled.go_package_prefix.default` value of your `buf.gen.yaml` file to
-have the package prefix named after your Go module. If our Go module's name, for example, is `github.com/sift-go-cli`, then change the `buf.gen.yaml` to `github.com/sift-go-cli/gen/protos/go`. Your
-`buf.gen.yaml` should now look like the following:
-
-```yaml
-version: v1
-managed:
-  enabled: true
-  go_package_prefix:
-    default: "github.com/sift-go-cli/gen/protos/go"
-plugins:
-  - plugin: buf.build/protocolbuffers/go:v1.28.1
-    out: gen/protos/go
-    opt: paths=source_relative
-  - plugin: go-vtproto
-    out: gen/protos/go
-    opt: paths=source_relative
-  - plugin: buf.build/grpc-ecosystem/gateway:v2.16.2
-    out: gen/protos/go
-    opt: paths=source_relative
-```
-
-Refer to your `go.mod` file for the name of your Go module.
-
-6. Inside of the root of your project directory you may now compile your protobufs:
+Once those are installed and your working directory is this project's root, compile the protobufs:
 
 ```bash
 $ buf generate protos
 ```
 
-Your project up to this point should look like the following (full depth not shown):
+Install dependencies:
 
-```
- sift-go-cli
- ├─ buf.gen.yaml
- ├─ gen
- │  └─ protos
- │     └─ go
- ├─ go.sum
- ├─ go.mod
- └─ protos
-    ├─ protoc-gen-openapiv2
-    │  └─ options
-    ├─ google
-    │  └─ api
-    └─ sift
-       ├─ runs
-       ├─ notifications
-       ├─ annotations
-       ├─ users
-       ├─ common
-       ├─ assets
-       ├─ tags
-       └─ annotation_logs
+```bash
+$ go get -d ./...
 ```
 
-7. Install any dependencies you might be missing that the generated code requires:
+Now execute the program by providing the partial string of the annotations you wish to query. In the following example
+we'll be querying for all annotations whose name matches the `voltage` substring in a case-insensitive manner.
 
 ```bash
-$ go get -d ./...
+$ go run . voltage
 ```
-
-8. Now your project should be ready to use the generated Go code to interact with Sift's gRPC API. Please refer to the example code for usage.
-If you are cloning the example repository, be sure to `$ cp .example.env .env` and set the appropriate variables. Comments in the `.example.env` files
-may prove useful.