add documentation (#45)

* wip: add some documentation Signed-off-by: everettraven <everettraven@gmail.com> * add more docs and logo Signed-off-by: everettraven <everettraven@gmail.com> --------- Signed-off-by: everettraven <everettraven@gmail.com>
everettraven · Dec 19, 2023 · dde1162 · dde1162
1 parent b09842c
commit dde1162
Show file tree

Hide file tree

Showing 12 changed files with 355 additions and 5 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/README.md b/README.md
@@ -1,12 +1,19 @@
 # buoy
 
-`buoy` is a declarative TUI dashboard for Kubernetes. You define your dashboard in a JSON file and it will fetch the information from your Kubernetes cluster and build a dashboard for viewing the requested content right in your terminal window.
+`buoy` is a declarative TUI dashboard for Kubernetes. You define your dashboard in a JSON or YAML file and it will fetch the information from your Kubernetes cluster and build a dashboard for viewing the requested content right in your terminal window.
 
 > [!NOTE]
 > This project is in the extremely early stages of development and is a hobby project. Use at your own risk.
 
 [![asciicast](https://asciinema.org/a/625808.svg)](https://asciinema.org/a/625808)
 
+## Motivation
+
+I created `buoy` because I do a lot of work on Kubernetes controllers. When I am making changes, I often find myself typing out a bunch of the same `kubectl ...` commands and switching between them. 
+Some of those commands are blocking (i.e `kubectl get logs -f ...`) and to keep them running while running other commands required opening a new terminal window and more typing.
+Since I was running pretty repetitive commands I thought there had to be a better solution. I looked through existing CLI tooling around this space, but none had a simple interface that followed the pattern of
+"define what you want to see and I'll show it to you". Thus `buoy` was created to fill this gap (and save me some time while delaying the inevitable arthritis).
+
 ## Quickstart
 
 - Clone the repository:
@@ -48,12 +55,11 @@ The `test.json` file contains samples for each of the different panel types that
 
 You can also specify a remote reference to a dashboard configuration file. It must be a valid URL and the response must be the raw YAML or JSON contents of the file.
 
-## Controls
-- `ctrl+c`, `q`, `esc` will quit the program and exit the tui
+## General Controls
+- `ctrl+c`, `q` will quit the program and exit the tui
 - `tab` will switch the active tab to the one to the right of the currently active tab
 - `shift+tab` will switch the active tab to the one to the left of the currently active tab
-- up and down arrow keys and mouse scroll will move up and down in the active tab
-- For tables you can use the left and right arrows to scroll horizontally
+- `ctrl+h` will open a more detailed help menu
 
 
 ## Contributing

diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,67 @@
+# buoy
+
+`buoy` is a declarative TUI dashboard for Kubernetes. You define your dashboard in a JSON or YAML file and it will fetch the information from your Kubernetes cluster and build a dashboard for viewing the requested content right in your terminal window.
+
+!> This project is in the extremely early stages of development and is a hobby project. Use at your own risk 
+
+[![asciicast](https://asciinema.org/a/625808.svg)](https://asciinema.org/a/625808)
+
+## Motivation
+
+I created `buoy` because I do a lot of work on Kubernetes controllers. When I am making changes, I often find myself typing out a bunch of the same `kubectl ...` commands and switching between them. 
+Some of those commands are blocking (i.e `kubectl get logs -f ...`) and to keep them running while running other commands required opening a new terminal window and more typing.
+Since I was running pretty repetitive commands I thought there had to be a better solution. I looked through existing CLI tooling around this space, but none had a simple interface that followed the pattern of
+"define what you want to see and I'll show it to you". Thus `buoy` was created to fill this gap (and save me some time while delaying the inevitable arthritis).
+
+## Quickstart
+
+- Clone the repository:
+```
+git clone https://github.com/everettraven/buoy.git
+```
+
+- `cd` into the cloned repository:
+```
+cd buoy
+```
+
+- Build the `buoy` binary:
+```
+make build
+```
+
+_OR_
+
+```
+go build -o buoy main.go
+```
+
+- Create a KinD cluster:
+```
+kind create cluster
+```
+
+- Run `buoy` using the `test.json` file:
+```
+./buoy test.json
+```
+
+The `test.json` file contains samples for each of the different panel types that `buoy` currently supports. As this is a hobby project very early in the development cycle there are some limitations and things are bound to not work as expected.
+
+`test.yaml` results in the exact same dashboard as `test.json` and exists to show YAML support.
+
+`buoy` uses https://github.com/tidwall/gjson for the path evaluation and extracting of values from resources. Please consult their documentation for valid path syntax.
+
+You can also specify a remote reference to a dashboard configuration file. It must be a valid URL and the response must be the raw YAML or JSON contents of the file.
+
+## General Controls
+- `ctrl+c`, `q` will quit the program and exit the tui
+- `tab` will switch the active tab to the one to the right of the currently active tab
+- `shift+tab` will switch the active tab to the one to the left of the currently active tab
+- `ctrl+h` will open a more detailed help menu
+
+## Contributing
+
+While this is a hobby project and in the early development stages, I'm more than happy to accept contributions. If you use `buoy` and find some problems or have some ideas for features/improvements, file an issue. If you want to contribute code, feel free to pick up any unassigned issues and create a pull request.
+
+Since this is a hobby project responses to issues and/or pull requests are likely to be slow.
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -0,0 +1,14 @@
+<!-- _coverpage.md -->
+
+![logo](_media/logo.png)
+
+# buoy
+
+> A declarative Kubernetes TUI dashboard
+
+[GitHub](https://github.com/everettraven/buoy)
+[Get Started](#buoy)
+
+<!-- background color -->
+
+![color](#ffffff)
diff --git a/docs/_media/logo.png b/docs/_media/logo.png
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,8 @@
+<!-- docs/_sidebar.md -->
+
+- [Introduction](/)
+- Panels
+    - [Table](panels/table.md)
+    - [Item](panels/item.md)
+    - [Logs](panels/logs.md)
+
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'buoy',
+      repo: 'https://github.com/everettraven/buoy',
+      loadSidebar: true,
+      coverpage: true,
+      subMaxLevel: 2,
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+
+  <!-- docsify-tabs (latest v1.x.x) -->
+  <script src="https://cdn.jsdelivr.net/npm/docsify-tabs@1"></script>
+
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
+
+</body>
+
+</html>
diff --git a/docs/panels/item.md b/docs/panels/item.md
@@ -0,0 +1,49 @@
+# Item
+
+The `item` panel is useful when you want to view the full YAML output of a particular resource. Typically this is useful when you want
+to watch for any changes to this specific object.
+
+## Example
+
+For this example, we want to keep an eye on a `Deployment` named `foo` in the `default` namespace
+
+<!-- tabs:start -->
+
+#### **JSON**
+```json
+{
+    "panels": [
+        {
+            "name": "Foo Deployment",
+            "group": "apps",
+            "version": "v1",
+            "kind": "Deployment",
+            "type": "item",
+            "key": {
+                "namespace": "default",
+                "name": "foo"
+            } 
+        }
+    ]
+}
+```
+
+#### **YAML**
+```yaml
+panels:
+  - name: Foo Deployment
+    group: apps
+    version: v1
+    kind: Deployment
+    type: item
+    key:
+      namespace: default
+      name: foo
+```
+
+<!-- tabs:end -->
+
+## Controls
+
+- Up and down arrow keys for navigating the viewport
+- Page Up and Page Down for jumping up and down in the viewport
diff --git a/docs/panels/logs.md b/docs/panels/logs.md
@@ -0,0 +1,95 @@
+# Logs
+
+The `logs` panel is great for following the logs of any resource that has a `spec.selector` field that maps
+to a `Pod`. It can also be directly pointed to an individual `Pod` to stream that `Pod`s logs.
+
+## Examples
+
+### Getting logs from a `Deployment`
+
+For this example, we are going to fetch some logs for a `Deployment` named `foo` in the `default` namespace
+
+<!-- tabs:start -->
+
+#### **JSON**
+```json
+{
+    "panels": [
+        {
+            "name": "Foo Logs",
+            "group": "apps",
+            "version": "v1",
+            "kind": "Deployment",
+            "type": "logs",
+            "key": {
+                "namespace": "default",
+                "name": "foo"
+            } 
+        }
+    ]
+}
+```
+
+#### **YAML**
+```yaml
+panels:
+  - name: Foo Logs
+    group: apps
+    version: v1
+    kind: Deployment
+    type: logs
+    key:
+      namespace: default
+      name: foo
+```
+
+<!-- tabs:end -->
+
+### Logs from a `Pod`
+
+For this example, we are going to fetch some logs for a `Pod` named `foo` in the `default` namespace
+
+<!-- tabs:start -->
+
+#### **JSON**
+```json
+{
+    "panels": [
+        {
+            "name": "Foo Logs",
+            "group": "",
+            "version": "v1",
+            "kind": "Pod",
+            "type": "logs",
+            "key": {
+                "namespace": "default",
+                "name": "foo"
+            } 
+        }
+    ]
+}
+```
+
+#### **YAML**
+```yaml
+panels:
+  - name: Foo Logs
+    group: ""
+    version: v1
+    kind: Pod
+    type: logs
+    key:
+      namespace: default
+      name: foo
+```
+
+<!-- tabs:end -->
+
+## Controls
+
+- Up and down arrow keys for navigating the viewport
+- Page Up and Page Down for jumping up and down in the viewport
+- `/` to enter a search mode. This will open a prompt for inputting a search query. When in search mode:
+    - `enter` / `return` executes the search query 
+    - `ctrl+s` toggles between fuzzy and strict search. strict search will only match lines strictly containing your search term.
+    - `esc` will exit search mode and return to the full logs
diff --git a/docs/panels/table.md b/docs/panels/table.md
@@ -0,0 +1,76 @@
+# Table
+
+The `table` panel is useful when you want to view a set of data in a structured format. For example, a good use case would be if 
+you wanted to view all the `Pod`s in a namespace.
+
+## Example
+
+For brevity, we will show an example of viewing all the `Pod`s in the `default` namespace. In this example, the information we want to know is:
+- Name
+- Labels
+- Phase
+- Containers
+
+<!-- tabs:start -->
+
+#### **JSON**
+```json
+{
+    "panels": [
+        {
+            "name": "All Pods",
+            "group": "",
+            "version": "v1",
+            "kind": "Pod",
+            "type": "table",
+            "namespace": "default",
+            "columns": [
+                {
+                    "header": "Name",
+                    "path": "metadata.name"
+                },
+                {
+                    "header": "Labels",
+                    "path": "metadata.labels"
+                },
+                {
+                    "header": "Phase",
+                    "path": "status.phase"
+                },
+                {
+                    "header": "Containers",
+                    "path": "spec.containers.#.name"
+                }
+            ]
+        }
+    ]
+}
+```
+
+#### **YAML**
+```yaml
+panels:
+  - name: All Pods
+    group: ""
+    version: v1
+    kind: Pod
+    type: table
+    namespace: default
+    columns:
+      - header: Name
+        path: metadata.name
+      - header: Labels
+        path: metadata.labels
+      - header: Phase
+        path: status.phase
+      - header: Containers
+        path: spec.containers.#.name
+```
+
+<!-- tabs:end -->
+
+## Controls
+
+- Up and down arrow keys for selecting rows
+- Left and right arrow keys for scrolling rows horizontally
+- `v` to toggle viewing the full YAML of the selected resource