[#1403] CLI Docs Revamp

.prettierignore

@@ -1,4 +1,4 @@
-**/*/cli/reference.md
+**/*/cli/usage.md
 **/*/changelog.md
 build/
 bazel-*

docs/cli-doc/generate_cli_docs.go

@@ -22,7 +22,7 @@ sidebar_label: %s
 
 `
 
-const basename = "reference"
+const basename = "usage"
 
 func main() {
 
@@ -39,44 +39,62 @@ func main() {
 	title := strings.Title(basename)
 	w.WriteString(fmt.Sprintf(fmTemplate, "Command "+title, title))
 
-	err = genMarkdownTreeCustom(cmd.RootCmd, w)
+	err = genMarkdownTreeCustom(cmd.RootCmd, w, "#")
 	if err != nil {
 		fmt.Println(err)
 	}
 
 }
 
-func genMarkdownTreeCustom(cmd *cobra.Command, w *bufio.Writer) error {
-
+func genMarkdownTreeCustom(cmd *cobra.Command, w *bufio.Writer, level string) error {
 	subcommands := cmd.Commands()
 	sort.Sort(byName(subcommands))
 
 	if len(subcommands) == 0 {
-		if err := genMarkdownCustom(cmd, w); err != nil {
-			return err
-		}
+		return genMarkdownCustom(cmd, w, level)
 	}
 
+	if err := genCommandNamespaceDoc(cmd, w, level); err != nil {
+		return err
+	}
 	for _, c := range subcommands {
 		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
-		if err := genMarkdownTreeCustom(c, w); err != nil {
+		if err := genMarkdownTreeCustom(c, w, level+"#"); err != nil {
 			return err
 		}
 	}
 
 	return nil
 }
 
-func genMarkdownCustom(cmd *cobra.Command, w *bufio.Writer) error {
+func genCommandNamespaceDoc(cmd *cobra.Command, w *bufio.Writer, level string) error {
 	cmd.InitDefaultHelpCmd()
 	cmd.InitDefaultHelpFlag()
 
 	name := cmd.CommandPath()
+	if name == "airy" {
+		return nil
+	}
+
+	header := strings.Title(strings.Replace(name, "airy", "", -1))
+	w.WriteString(level + " " + strings.Trim(header, " ") + "\n\n")
+	w.WriteString(cmd.Short + "\n\n")
+	w.Flush()
+	return nil
+}
+
+func genMarkdownCustom(cmd *cobra.Command, w *bufio.Writer, level string) error {
+	cmd.InitDefaultHelpCmd()
+	cmd.InitDefaultHelpFlag()
+	name := cmd.CommandPath()
+
 	header := strings.Title(strings.Replace(name, "airy", "", -1))
+	headerParts := strings.Split(header, " ")
+	header = headerParts[len(headerParts)-1]
 
-	w.WriteString("## " + strings.Trim(header, " ") + "\n\n")
+	w.WriteString(level + " " + strings.Trim(header, " ") + "\n\n")
 	w.WriteString(cmd.Short + "\n\n")
 	if len(cmd.Long) > 0 {
 		w.WriteString("#### Synopsis\n\n")

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/usage.md#init) will create a `cli.yaml` file which stores
 your `apiHost` and `apiJwtToken`:
 
 ```bash

docs/docs/cli/reference.md → docs/docs/cli/usage.md

@@ -1,9 +1,13 @@
 ---
-title: Command Reference
-sidebar_label: Reference
+title: Command Usage
+sidebar_label: Usage
 ---
 
-## Api Endpoint
+## Api
+
+Interacts with the Airy Core HTTP API
+
+### Endpoint
 
 Get the endpoint of the Airy Core API
 
@@ -27,7 +31,7 @@ airy api endpoint [flags]
 
 ***
 
-## Api Login
+### Login
 
 Login into an Airy Core instance
 
@@ -53,7 +57,7 @@ airy api login [flags]
 
 ***
 
-## Api Signup
+### Signup
 
 Signs users up in Airy Core
 
@@ -81,7 +85,11 @@ airy api signup [flags]
 
 ***
 
-## Config Apply
+## Config
+
+Manages an Airy Core instance via airy.yaml
+
+### Apply
 
 Applies configuration values from airy.yaml configuration to an Airy Core instance
 

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.

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).
 

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/usage.md#config-apply) by running the
+following [Airy CLI](/cli/introduction.md) command.
 
 ```bash
 airy config apply --config ./airy.yaml

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 />}

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

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>
 

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/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/usage.md#ui):
 
 ```bash
 airy ui

docs/sidebars.js

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

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/usage.md /tmp/
 bazel run //docs/cli-doc:generate_cli_docs
-cmp docs/docs/cli/reference.md  /tmp/reference.md
+cmp docs/docs/cli/usage.md  /tmp/usage.md
 echo
 echo "Running Prettier, Buildifier and Checkstyle"
 bazel test --test_tag_filters=lint //...