Create structure for long descriptions and examples

Author: olufunbi

Makefile

@@ -35,12 +35,12 @@ dryinstall: go-build
 
 .PHONY: install
 install: uninstall go-build
-	@sudo mkdir ~/.$(BINARY_NAME) -p
-	@sudo mkdir ~/.$(BINARY_NAME)/config -p
-	@sudo mkdir ~/.$(BINARY_NAME)/profiles -p
+	@sudo mkdir -p ~/.$(BINARY_NAME)
+	@sudo mkdir -p ~/.$(BINARY_NAME)/config
+	@sudo mkdir -p ~/.$(BINARY_NAME)/profiles
 	@sudo cp ./tests/config.json ~/.$(BINARY_NAME)/config/config.json
 	@sudo mv $(SOURCE_DIR)/$(BINARY_NAME) /usr/local/bin/$(BINARY_NAME)
 	@sudo chmod -R 777 ~/.$(BINARY_NAME)
 	@echo "✅ $(BINARY_NAME) installed..!"
 	@echo
-	make clean
+	@$(MAKE) clean

src/cmd/create/flink_cluster.go

@@ -23,11 +23,18 @@ var (
 	replicas    uint8  = 1
 )
 
+// Description and Examples for creating flink clsuters
+var (
+	flinkLongDesc = utils.LongDesc(`
+		Create a flink cluster with specified requirments.
+		`)
+)
+
 // infoCmd represents the info command
 var FlinkClusterCmd = &cobra.Command{
 	Use:   "flink-cluster",
 	Short: "create a flink cluster",
-	Long:  `create a flink cluster`,
+	Long:  flinkLongDesc,
 	Args:  cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		profile, err := utils.ValidateCluster()

src/cmd/deploy/pipeline.go

@@ -24,6 +24,12 @@ import (
 	"k8s.io/client-go/rest"
 )
 
+var (
+	deployLongDesc = utils.LongDesc(`
+		Deploy an Apache Beam pipeline on a specified Operator.
+		`)
+)
+
 var (
 	flinkCluster          string       = ""
 	PVCMountPath          string       = "/pvc"
@@ -45,7 +51,7 @@ type FileInfo struct {
 var PipelineCmd = &cobra.Command{
 	Use:   "pipeline [FILE]",
 	Short: "Deploy an Apache Beam pipeline",
-	Long:  "Deploy an Apache Beam pipeline on a specified Operator.",
+	Long:  deployLongDesc,
 	Args:  cobra.ExactArgs(1),
 	Run:   DeployPipeline,
 }

src/cmd/info/cluster.go

@@ -5,15 +5,29 @@ import (
 	"time"
 
 	info_handler "github.com/BeamStackProj/beamstack-cli/src/handlers/info"
+	"github.com/BeamStackProj/beamstack-cli/src/utils"
 	"github.com/spf13/cobra"
 	v1 "k8s.io/api/core/v1"
 )
 
+var (
+	clusterLongDesc = utils.LongDesc(`
+		This command fetches detailed information about the Kubernetes cluster,
+  	including the status of each node and the overall health of the cluster.
+		`)
+
+	clusterExample = utils.Examples(`
+  # Get cluster information
+  beamstack info cluster
+	`)
+)
+
 // infoCmd represents the info command
 var ClusterCmd = &cobra.Command{
-	Use:   "cluster",
-	Short: "get information the kubernetes cluster",
-	Long:  `Cluster information including nodes, and current workloads`,
+	Use:     "cluster",
+	Short:   "get information the kubernetes cluster",
+	Long:    clusterLongDesc,
+	Example: clusterExample,
 	Run: func(cmd *cobra.Command, args []string) {
 		clusterHealth, err := info_handler.Health()
 

src/cmd/info/info.go

@@ -11,11 +11,18 @@ import (
 	"github.com/spf13/viper"
 )
 
+// Long Description and Example initizalization
+var (
+	infoLongDesc = utils.LongDesc(`
+		This command displays detailed information about specified resources such as clusters.
+		`)
+)
+
 // infoCmd represents the info command
 var InfoCmd = &cobra.Command{
 	Use:   "info",
 	Short: "Pallete that contains information based commands",
-	Long:  `Pallete that contains information based commands`,
+	Long:  infoLongDesc,
 	Run: func(cmd *cobra.Command, args []string) {
 		ctx, err := utils.GetCurrentContext()
 		if err != nil {

src/cmd/initialize/init.go

@@ -12,10 +12,16 @@ import (
 	"github.com/spf13/viper"
 )
 
+var (
+	initLongDesc = utils.LongDesc(`
+		Initialize Beamstack in a new Kubernetes environment, setting up essential configurations and prerequisites.
+		`)
+)
+
 var InitCmd = &cobra.Command{
 	Use:   "init",
 	Short: "Initialize beamstack on cluster",
-	Long:  `Initialize Beamstack in a new Kubernetes environment, setting up essential configurations and prerequisites.`,
+	Long:  initLongDesc,
 	Run:   runInit,
 }
 

src/cmd/open/dashboard.go

@@ -16,11 +16,18 @@ import (
 	"k8s.io/client-go/kubernetes"
 )
 
+// Description and Examples for opening grafana dashboard
+var (
+	openDashboardLongDesc = utils.LongDesc(`
+		This command opens up the GUI for the Grafana Dashbaord.
+		`)
+)
+
 // infoCmd represents the info command
 var DashboardCmd = &cobra.Command{
 	Use:   "dashboard",
 	Short: "opens up grafana dashboard",
-	Long:  `opens up grafana dashboard`,
+	Long:  openDashboardLongDesc,
 	Run: func(cmd *cobra.Command, args []string) {
 		LocalPort, err := cmd.Flags().GetUint16("localport")
 		if err != nil {

src/cmd/open/flink_cluster.go

@@ -16,11 +16,18 @@ import (
 	"k8s.io/client-go/kubernetes"
 )
 
+// Description and Examples for opening grafana dashboard
+var (
+	openFlinkClusterLongDesc = utils.LongDesc(`
+		This command opens up the GUI for the flink clusters and forward it to a specified local port.
+		`)
+)
+
 // infoCmd represents the info command
 var FlinkClusterCmd = &cobra.Command{
 	Use:   "flink",
 	Short: "opens up flink cluster ui",
-	Long:  `opens up flink cluster ui`,
+	Long:  openFlinkClusterLongDesc,
 	Args:  cobra.ExactArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		LocalPort, err := cmd.Flags().GetUint16("localport")

src/utils/documentation.go

@@ -0,0 +1,66 @@
+package utils
+
+import (
+	"strings"
+)
+
+var (
+	// AlphaDisclaimer to be places at the end of description of commands in alpha release
+	AlphaDisclaimer = `
+		Alpha Disclaimer: this command is currently alpha.
+	`
+
+	// MacroCommandLongDescription provide a standard description for "macro" commands
+	MacroCommandLongDescription = LongDesc(`
+		This command is not meant to be run on its own. See list of available subcommands.
+	`)
+)
+
+func LongDesc(s string) string {
+	// Strip beginning and trailing space characters (including empty lines) and split the lines into a slice
+	lines := strings.Split(strings.TrimSpace(s), "\n")
+
+	output := []string{}
+	paragraph := []string{}
+
+	for _, line := range lines {
+		// Remove indentation and trailing spaces from the current line
+		trimmedLine := strings.TrimSpace(line)
+		if trimmedLine == "" {
+			if len(paragraph) > 0 {
+				output = append(output, strings.Join(paragraph, " ")+"\n")
+				paragraph = []string{}
+			}
+		} else {
+			// Non-empty text line, append it to the current paragraph
+			paragraph = append(paragraph, trimmedLine)
+			if strings.HasSuffix(line, "  ") {
+				output = append(output, strings.Join(paragraph, " "))
+				paragraph = []string{}
+			}
+		}
+	}
+
+	output = append(output, strings.Join(paragraph, " "))
+
+	// Join all the paragraphs together with new lines in between them.
+	return strings.Join(output, "\n")
+}
+
+// Examples is designed to help with producing examples for command line usage.
+func Examples(s string) string {
+	trimmedText := strings.TrimSpace(s)
+	if trimmedText == "" {
+		return ""
+	}
+
+	const indent = `  `
+	inLines := strings.Split(trimmedText, "\n")
+	outLines := make([]string, 0, len(inLines))
+
+	for _, line := range inLines {
+		outLines = append(outLines, indent+strings.TrimSpace(line))
+	}
+
+	return strings.Join(outLines, "\n")
+}