[#1403] CLI Docs Revamp

airyhq · Mar 31, 2021 · 18c5ec0 · 18c5ec0
1 parent 68e0275
commit 18c5ec0
Show file tree

Hide file tree

Showing 12 changed files with 28 additions and 25 deletions.
diff --git a/docs/cli-doc/generate_cli_docs.go b/docs/cli-doc/generate_cli_docs.go
@@ -22,7 +22,7 @@ sidebar_label: %s
 
 `
 
-const basename = "reference"
+const basename = "cli-usage"
 
 func main() {
 
@@ -36,8 +36,7 @@ func main() {
 	defer f.Close()
 	w := bufio.NewWriter(f)
 
-	title := strings.Title(basename)
-	w.WriteString(fmt.Sprintf(fmTemplate, "Command "+title, title))
+	w.WriteString(fmt.Sprintf(fmTemplate, "CLI Usage", "CLI Usage"))
 
 	err = genMarkdownTreeCustom(cmd.RootCmd, w)
 	if err != nil {

diff --git a/docs/docs/cli/reference.md → docs/docs/cli/cli-usage.md b/docs/docs/cli/reference.md → docs/docs/cli/cli-usage.md
@@ -1,6 +1,6 @@
 ---
-title: Command Reference
-sidebar_label: Reference
+title: CLI Usage
+sidebar_label: CLI Usage
 ---
 
 ## Api Endpoint

diff --git a/docs/docs/cli/installation.md → docs/docs/cli/introduction.md b/docs/docs/cli/installation.md → docs/docs/cli/introduction.md
@@ -1,6 +1,6 @@
 ---
 title: Install the Airy CLI
-sidebar_label: Installation
+sidebar_label: Introduction
 hide_table_of_contents: false
 ---
 
@@ -16,13 +16,17 @@ Airy Core instances directly from your terminal.
 
 </TLDR>
 
+import Script from "@site/src/components/Script";
+
+<Script data-cols="120" data-rows="32" id="asciicast-403849" src="https://asciinema.org/a/403849.js"></Script>
+
 Installing the Airy CLI is easy and straightforward. You can follow the next
 steps for a quick setup:
 
-- [Step 1: Check the requirements](installation.md#step-1-check-the-requirements)
-- [Step 2: Install the Airy CLI](installation.md#step-2-install-the-airy-cli)
-- [Step 3: Verify your installation](installation.md#step-3-verify-your-installation)
-- [Step 4: Initialize the setup](installation.md#step-4-initialize-the-setup)
+- [Step 1: Check the requirements](introduction.md#step-1-check-the-requirements)
+- [Step 2: Install the Airy CLI](introduction.md#step-2-install-the-airy-cli)
+- [Step 3: Verify your installation](introduction.md#step-3-verify-your-installation)
+- [Step 4: Initialize the setup](introduction.md#step-4-initialize-the-setup)
 
 ### Step 1: Check the requirements
 
@@ -31,7 +35,7 @@ on macOS, Linux and Windows and we provide pre-built executable binaries for
 **x86-64**.
 
 If you are running on a different platform you can also [build it
-yourself](installation.md#building-from-source).
+yourself](introduction.md#building-from-source).
 
 ### Step 2: Install the Airy CLI
 
@@ -131,7 +135,7 @@ airy version
 
 ### Step 4: Initialize the setup
 
-The [airy init](cli/reference.md#init) will create a `cli.yaml` file which stores
+The [airy init](cli/cli-usage.md#init) will create a `cli.yaml` file which stores
 your `apiHost` and `apiJwtToken`:
 
 ```bash

diff --git a/docs/docs/concepts/architecture.md b/docs/docs/concepts/architecture.md
@@ -53,4 +53,4 @@ and reloading the appropriate `Airy Components` based on the provided configurat
 
 Every release features a command line binary, used to configure and fetch status
 information from your Airy Core instance. This tool is referred to as the [Airy
-CLI](/cli/installation.md) throughout the documentation.
+CLI](/cli/introduction.md) throughout the documentation.
diff --git a/docs/docs/getting-started/installation/aws.md b/docs/docs/getting-started/installation/aws.md
@@ -29,7 +29,7 @@ Apart from the EKS cluster, the installation will create all the necessary AWS r
 
 For creating the cluster you would need to setup your local AWS environment, by [configuring your local AWS profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) for the AWS account where all the resources will be created.
 
-Download and install the [Airy CLI](cli/installation.md).
+Download and install the [Airy CLI](cli/introduction.md).
 
 Export your AWS_PROFILE as described in the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).
 

diff --git a/docs/docs/getting-started/installation/configuration.md b/docs/docs/getting-started/installation/configuration.md
@@ -95,8 +95,8 @@ monitor or debug the **Airy Core**.
 ## Applying the configuration
 
 If you made changes in `airy.yaml` and want to apply it to your instance you can
-use the [airy config apply](/cli/reference.md#config-apply) by running the
-following [Airy CLI](/cli/installation.md) command.
+use the [airy config apply](/cli/cli-usage.md#config-apply) by running the
+following [Airy CLI](/cli/introduction.md) command.
 
 ```bash
 airy config apply --config ./airy.yaml

diff --git a/docs/docs/getting-started/installation/introduction.md b/docs/docs/getting-started/installation/introduction.md
@@ -17,7 +17,7 @@ You can deploy Airy Core in many different ways: **locally** or
 
  </TLDR>
 
-We recommend to [install](/cli/installation.md) the Airy CLI first which will
+We recommend to [install](/cli/introduction.md) the Airy CLI first which will
 aid you in the process of installing and managing your Airy Core instance. It is
 easy to install and works on macOS, Windows, and Linux.
 
@@ -29,7 +29,7 @@ icon={<RocketSVG />}
 iconInvertible={true}
 title='CLI'
 description='Install the Airy Core CLI application'
-link='/cli/installation'
+link='/cli/introduction'
 />
 <ButtonBox
 icon={<Minikube />}

diff --git a/docs/docs/getting-started/installation/minikube.md b/docs/docs/getting-started/installation/minikube.md
@@ -16,7 +16,7 @@ your local machine using [minikube](https://minikube.sigs.k8s.io/).
 
 First download and install minikube from their [release
 page](https://github.com/kubernetes/minikube/releases) and the [Airy
-CLI](cli/installation.md). Now you can run this command, which will create a new
+CLI](cli/introduction.md). Now you can run this command, which will create a new
 minikube cluster on your system and install Airy core on it:
 
 ```bash

diff --git a/docs/docs/getting-started/introduction.md b/docs/docs/getting-started/introduction.md
@@ -63,7 +63,7 @@ conversational data to wherever you need it.
     iconInvertible={true}
     title='Start Installation' 
     description='Install Airy with our CLI, locally or in the cloud' 
-    link='cli/installation'
+    link='cli/introduction'
 />
 </ButtonBoxList>
 

diff --git a/docs/docs/ui/quickstart.md b/docs/docs/ui/quickstart.md
@@ -30,7 +30,7 @@ To register a new user in the Airy Core you can use the **users.signup**
 [endpoint](api/endpoints/users.md#signup).
 
 Alternatively you can run the
-following [CLI command](cli/reference.md#api-signup) to create a default user.
+following [CLI command](cli/cli-usage.md#api-signup) to create a default user.
 You can also pass your own email and password as parameters. Otherwise these default
 credentials will be used:
 
@@ -45,7 +45,7 @@ airy api signup
 
 ## Step 2: Open the UI
 
-Run this [CLI command](cli/reference.md#ui):
+Run this [CLI command](cli/cli-usage.md#ui):
 
 ```bash
 airy ui

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -13,7 +13,7 @@ module.exports = {
           ],
         },
         {
-          'Command Line Interface': ['cli/installation', 'cli/reference'],
+          'Command Line Interface': ['cli/introduction', 'cli/cli-usage'],
         },
         'getting-started/quickstart',
         'getting-started/troubleshooting',

diff --git a/scripts/lint.sh b/scripts/lint.sh
@@ -7,9 +7,9 @@ bazel run //infrastructure/tools/topics:app > /tmp/topics-output
 cmp /tmp/topics-output infrastructure/helm-chart/charts/provisioning/templates/kafka-create-topics.yaml
 echo
 echo "Check cli doc is in sync"
-cp docs/docs/cli/reference.md /tmp/
+cp docs/docs/cli/cli-usage.md /tmp/
 bazel run //docs/cli-doc:generate_cli_docs
-cmp docs/docs/cli/reference.md  /tmp/reference.md
+cmp docs/docs/cli/cli-usage.md  /tmp/cli-usage.md
 echo
 echo "Running Prettier, Buildifier and Checkstyle"
 bazel test --test_tag_filters=lint //...