Cluster- updating cmd files for documentation

The description and examples are updated for the airshipctl
commands, which will be inturn used for generating documentation.
Please ignore the .md file changes in this PS. They are added for zuul
gates to pass. Here is the PS with generated documention
files https://review.opendev.org/c/airship/airshipctl/+/789250

Relates-To: #280
Change-Id: I7c088528842ff859f502d4484ff9a3847ebb1177

cmd/cluster/checkexpiration/checkexpiration.go

@@ -25,29 +25,28 @@ import (
 
 const (
 	checkLong = `
-Displays a list of certificate expirations from both the management and
-workload clusters, or in a self-managed cluster. Checks for TLS Secrets,
-kubeconf secrets (which gets created while creating the workload cluster) and
-also the node certificates present inside /etc/kubernetes/pki directory for
-each node`
+Displays a list of certificate along with expirations from both the management and workload clusters, or in a
+self-managed cluster. Checks for TLS Secrets, kubeconf secrets (which gets created while creating the
+workload cluster) and also the node certificates present inside /etc/kubernetes/pki directory for each node.
+`
 
 	checkExample = `
-# To display all the expiring entities in the cluster
-airshipctl cluster check-certificate-expiration --kubeconfig testconfig
+To display all the expiring entities in the cluster
+# airshipctl cluster check-certificate-expiration --kubeconfig testconfig
 
-# To display the entities whose expiration is within threshold of 30 days
-airshipctl cluster check-certificate-expiration -t 30 --kubeconfig testconfig
+To display the entities whose expiration is within threshold of 30 days
+# airshipctl cluster check-certificate-expiration -t 30 --kubeconfig testconfig
 
-# To output the contents to json (default operation)
-airshipctl cluster check-certificate-expiration -o json --kubeconfig testconfig
+To output the contents to json (default operation)
+# airshipctl cluster check-certificate-expiration -o json --kubeconfig testconfig
 or
-airshipctl cluster check-certificate-expiration --kubeconfig testconfig
+# airshipctl cluster check-certificate-expiration --kubeconfig testconfig
 
-# To output the contents to yaml
-airshipctl cluster check-certificate-expiration -o yaml --kubeconfig testconfig
+To output the contents to yaml
+# airshipctl cluster check-certificate-expiration -o yaml --kubeconfig testconfig
 
-# To output the contents whose expiration is within 30 days to yaml
-airshipctl cluster check-certificate-expiration -t 30 -o yaml --kubeconfig testconfig
+To output the contents whose expiration is within 30 days to yaml
+# airshipctl cluster check-certificate-expiration -t 30 -o yaml --kubeconfig testconfig
 `
 
 	kubeconfigFlag = "kubeconfig"
@@ -62,24 +61,22 @@ func NewCheckCommand(cfgFactory config.Factory) *cobra.Command {
 	}
 
 	checkCmd := &cobra.Command{
-		Use:     "check-certificate-expiration",
-		Short:   "Check for expiring TLS certificates, secrets and kubeconfigs in the kubernetes cluster",
+		Use: "check-certificate-expiration",
+		Short: "Airshipctl command to check expiring TLS certificates, " +
+			"secrets and kubeconfigs in the kubernetes cluster",
 		Long:    checkLong[1:],
 		Example: checkExample,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return c.RunE(cmd.OutOrStdout())
 		},
 	}
 
-	checkCmd.Flags().IntVarP(&c.Options.Threshold, "threshold", "t", -1,
-		"The max expiration threshold in days before a certificate is"+
-			" expiring. Displays all the certificates by default")
-	checkCmd.Flags().StringVarP(&c.Options.FormatType, "output", "o", "json", "Convert "+
-		"output to yaml or json")
+	checkCmd.Flags().StringVarP(&c.Options.FormatType, "output", "o", "json", "convert output to yaml or json")
+	checkCmd.Flags().StringVar(&c.Options.KubeContext, "kubecontext", "", "kubeconfig context to be used")
 	checkCmd.Flags().StringVar(&c.Options.Kubeconfig, kubeconfigFlag, "",
-		"Path to kubeconfig associated with cluster being managed")
-	checkCmd.Flags().StringVar(&c.Options.KubeContext, "kubecontext", "",
-		"Kubeconfig context to be used")
+		"path to kubeconfig associated with cluster being managed")
+	checkCmd.Flags().IntVarP(&c.Options.Threshold, "threshold", "t", -1,
+		"the max expiration threshold in days before a certificate is expiring. Displays all the certificates by default")
 
 	err := checkCmd.MarkFlagRequired(kubeconfigFlag)
 	if err != nil {

cmd/cluster/checkexpiration/testdata/TestCheckExpirationGoldenOutput/check-expiration-with-help.golden

@@ -1,35 +1,33 @@
-Displays a list of certificate expirations from both the management and
-workload clusters, or in a self-managed cluster. Checks for TLS Secrets,
-kubeconf secrets (which gets created while creating the workload cluster) and
-also the node certificates present inside /etc/kubernetes/pki directory for
-each node
+Displays a list of certificate along with expirations from both the management and workload clusters, or in a
+self-managed cluster. Checks for TLS Secrets, kubeconf secrets (which gets created while creating the
+workload cluster) and also the node certificates present inside /etc/kubernetes/pki directory for each node.
 
 Usage:
   check-certificate-expiration [flags]
 
 Examples:
 
-# To display all the expiring entities in the cluster
-airshipctl cluster check-certificate-expiration --kubeconfig testconfig
+To display all the expiring entities in the cluster
+# airshipctl cluster check-certificate-expiration --kubeconfig testconfig
 
-# To display the entities whose expiration is within threshold of 30 days
-airshipctl cluster check-certificate-expiration -t 30 --kubeconfig testconfig
+To display the entities whose expiration is within threshold of 30 days
+# airshipctl cluster check-certificate-expiration -t 30 --kubeconfig testconfig
 
-# To output the contents to json (default operation)
-airshipctl cluster check-certificate-expiration -o json --kubeconfig testconfig
+To output the contents to json (default operation)
+# airshipctl cluster check-certificate-expiration -o json --kubeconfig testconfig
 or
-airshipctl cluster check-certificate-expiration --kubeconfig testconfig
+# airshipctl cluster check-certificate-expiration --kubeconfig testconfig
 
-# To output the contents to yaml
-airshipctl cluster check-certificate-expiration -o yaml --kubeconfig testconfig
+To output the contents to yaml
+# airshipctl cluster check-certificate-expiration -o yaml --kubeconfig testconfig
 
-# To output the contents whose expiration is within 30 days to yaml
-airshipctl cluster check-certificate-expiration -t 30 -o yaml --kubeconfig testconfig
+To output the contents whose expiration is within 30 days to yaml
+# airshipctl cluster check-certificate-expiration -t 30 -o yaml --kubeconfig testconfig
 
 
 Flags:
   -h, --help                 help for check-certificate-expiration
-      --kubeconfig string    Path to kubeconfig associated with cluster being managed
-      --kubecontext string   Kubeconfig context to be used
-  -o, --output string        Convert output to yaml or json (default "json")
-  -t, --threshold int        The max expiration threshold in days before a certificate is expiring. Displays all the certificates by default (default -1)
+      --kubeconfig string    path to kubeconfig associated with cluster being managed
+      --kubecontext string   kubeconfig context to be used
+  -o, --output string        convert output to yaml or json (default "json")
+  -t, --threshold int        the max expiration threshold in days before a certificate is expiring. Displays all the certificates by default (default -1)

cmd/cluster/cluster.go

@@ -25,7 +25,7 @@ import (
 const (
 	// TODO: (kkalynovskyi) Add more description when more subcommands are added
 	clusterLong = `
-This command provides capabilities for interacting with a Kubernetes cluster,
+Provides capabilities for interacting with a Kubernetes cluster,
 such as getting status and deploying initial infrastructure.
 `
 )
@@ -34,7 +34,7 @@ such as getting status and deploying initial infrastructure.
 func NewClusterCommand(cfgFactory config.Factory) *cobra.Command {
 	clusterRootCmd := &cobra.Command{
 		Use:   "cluster",
-		Short: "Manage Kubernetes clusters",
+		Short: "Airshipctl command to manage kubernetes clusters",
 		Long:  clusterLong[1:],
 	}
 

cmd/cluster/get_kubeconfig.go

@@ -23,30 +23,32 @@ import (
 
 const (
 	getKubeconfigLong = `
-Retrieve cluster kubeconfig and print it to stdout
+Retrieves kubeconfig of the cluster and prints it to stdout.
+
 If you specify clusterName, kubeconfig will have a CurrentContext set to clusterName and
-will have this context defined
+will have its context defined.
+
 If you don't specify clusterName, kubeconfig will have multiple contexts for every cluster
-in the airship site. Context names will correspond to cluster names. CurrentContext will be empty
+in the airship site. Context names will correspond to cluster names. CurrentContext will be empty.
 `
 	getKubeconfigExample = `
-# Retrieve target-cluster kubeconfig
-airshipctl cluster get-kubeconfig target-cluster
+Retrieve target-cluster kubeconfig
+# airshipctl cluster get-kubeconfig target-cluster
 
-# Retrieve kubeconfig for the entire site; the kubeconfig will have context for every cluster
-airshipctl cluster get-kubeconfig
+Retrieve kubeconfig for the entire site; the kubeconfig will have context for every cluster
+# airshipctl cluster get-kubeconfig
 `
 )
 
 // NewGetKubeconfigCommand creates a command which retrieves cluster kubeconfig
 func NewGetKubeconfigCommand(cfgFactory config.Factory) *cobra.Command {
 	opts := &cluster.GetKubeconfigCommand{}
 	cmd := &cobra.Command{
-		Use:     "get-kubeconfig [clusterName]",
-		Short:   "Retrieve kubeconfig for a desired cluster",
+		Use:     "get-kubeconfig CLUSTER_NAME",
+		Short:   "Airshipctl command to retrieve kubeconfig for a desired cluster",
 		Long:    getKubeconfigLong[1:],
 		Args:    GetKubeconfArgs(opts),
-		Example: getKubeconfigExample[1:],
+		Example: getKubeconfigExample,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return opts.RunE(cfgFactory, cmd.OutOrStdout())
 		},

cmd/cluster/list.go

@@ -22,12 +22,15 @@ import (
 )
 
 const (
-	listShort   = "Retrieve the list of defined clusters"
+	listLong = `
+Retrieve and list the defined clusters in the table form or display just the name as specified.
+`
+
 	listExample = `
-# Retrieve cluster list
-airshipctl cluster list --airshipconf /tmp/airconfig
-airshipctl cluster list -o table
-airshipctl cluster list -o name
+Retrieve list of clusters
+# airshipctl cluster list --airshipconf /tmp/airconfig
+# airshipctl cluster list -o table
+# airshipctl cluster list -o name
 `
 )
 
@@ -36,15 +39,13 @@ func NewListCommand(cfgFactory config.Factory) *cobra.Command {
 	o := &phase.ClusterListCommand{Factory: cfgFactory}
 	cmd := &cobra.Command{
 		Use:     "list",
-		Short:   listShort,
-		Example: listExample[1:],
+		Short:   "Airshipctl command to get and list defined clusters",
+		Long:    listLong,
+		Example: listExample,
 		RunE:    listRunE(o),
 	}
 	flags := cmd.Flags()
-	flags.StringVarP(&o.Format,
-		"output", "o", "name", "'table' "+
-			"and 'name' are available "+
-			"output formats")
+	flags.StringVarP(&o.Format, "output", "o", "name", "output formats. Supported options are 'table' and 'name'")
 
 	return cmd
 }

cmd/cluster/resetsatoken/resetsatoken.go

@@ -24,19 +24,19 @@ import (
 
 const (
 	resetLong = `
-Use to reset/rotate the Service Account(SA) tokens and additionally restart the
-corresponding pods to get the latest token data reflected in the pod spec
+Reset/rotate the Service Account(SA) tokens and additionally restart the corresponding pods to get the latest
+token data reflected in the pod spec.
 
-Secret-namespace is a mandatory field and secret-name is optional. If secret-
-name is not given, all the SA tokens in that particular namespace is considered,
-else only that particular input secret-name`
+Secret-namespace is a mandatory flag and secret-name is optional. If secret-name is not given, all the SA tokens
+in that particular namespace is considered, else only that particular input secret-name.
+`
 
 	resetExample = `
-# To rotate a particular SA token
-airshipctl cluster rotate-sa-token -n cert-manager -s cert-manager-token-vvn9p
+To rotate a particular SA token
+# airshipctl cluster rotate-sa-token -n cert-manager -s cert-manager-token-vvn9p
 
-# To rotate all the SA tokens in cert-manager namespace
-airshipctl cluster rotate-sa-token -n cert-manager
+To rotate all the SA tokens in cert-manager namespace
+# airshipctl cluster rotate-sa-token -n cert-manager
 `
 )
 
@@ -49,7 +49,7 @@ func NewResetCommand(cfgFactory config.Factory) *cobra.Command {
 
 	resetCmd := &cobra.Command{
 		Use:     "rotate-sa-token",
-		Short:   "Rotate tokens of Service Accounts",
+		Short:   "Airshipctl command to rotate tokens of Service Account(s)",
 		Long:    resetLong[1:],
 		Example: resetExample,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -62,7 +62,7 @@ func NewResetCommand(cfgFactory config.Factory) *cobra.Command {
 	resetCmd.Flags().StringVarP(&r.Options.SecretName, "secret-name", "s", "",
 		"name of the secret containing Service Account Token")
 	resetCmd.Flags().StringVar(&r.Options.Kubeconfig, "kubeconfig", "",
-		"Path to kubeconfig associated with cluster being managed")
+		"path to kubeconfig associated with cluster being managed")
 
 	err := resetCmd.MarkFlagRequired("secret-namespace")
 	if err != nil {

cmd/cluster/resetsatoken/testdata/TestResetTokenGoldenOutput/reset-with-help.golden

@@ -1,24 +1,23 @@
-Use to reset/rotate the Service Account(SA) tokens and additionally restart the
-corresponding pods to get the latest token data reflected in the pod spec
+Reset/rotate the Service Account(SA) tokens and additionally restart the corresponding pods to get the latest
+token data reflected in the pod spec.
 
-Secret-namespace is a mandatory field and secret-name is optional. If secret-
-name is not given, all the SA tokens in that particular namespace is considered,
-else only that particular input secret-name
+Secret-namespace is a mandatory flag and secret-name is optional. If secret-name is not given, all the SA tokens
+in that particular namespace is considered, else only that particular input secret-name.
 
 Usage:
   rotate-sa-token [flags]
 
 Examples:
 
-# To rotate a particular SA token
-airshipctl cluster rotate-sa-token -n cert-manager -s cert-manager-token-vvn9p
+To rotate a particular SA token
+# airshipctl cluster rotate-sa-token -n cert-manager -s cert-manager-token-vvn9p
 
-# To rotate all the SA tokens in cert-manager namespace
-airshipctl cluster rotate-sa-token -n cert-manager
+To rotate all the SA tokens in cert-manager namespace
+# airshipctl cluster rotate-sa-token -n cert-manager
 
 
 Flags:
   -h, --help                      help for rotate-sa-token
-      --kubeconfig string         Path to kubeconfig associated with cluster being managed
+      --kubeconfig string         path to kubeconfig associated with cluster being managed
   -s, --secret-name string        name of the secret containing Service Account Token
   -n, --secret-namespace string   namespace of the Service Account Token

cmd/cluster/testdata/TestNewClusterCommandGoldenOutput/cluster-cmd-with-help.golden

@@ -1,15 +1,15 @@
-This command provides capabilities for interacting with a Kubernetes cluster,
+Provides capabilities for interacting with a Kubernetes cluster,
 such as getting status and deploying initial infrastructure.
 
 Usage:
   cluster [command]
 
 Available Commands:
-  check-certificate-expiration Check for expiring TLS certificates, secrets and kubeconfigs in the kubernetes cluster
-  get-kubeconfig               Retrieve kubeconfig for a desired cluster
+  check-certificate-expiration Airshipctl command to check expiring TLS certificates, secrets and kubeconfigs in the kubernetes cluster
+  get-kubeconfig               Airshipctl command to retrieve kubeconfig for a desired cluster
   help                         Help about any command
-  list                         Retrieve the list of defined clusters
-  rotate-sa-token              Rotate tokens of Service Accounts
+  list                         Airshipctl command to get and list defined clusters
+  rotate-sa-token              Airshipctl command to rotate tokens of Service Account(s)
   status                       Retrieve statuses of deployed cluster components
 
 Flags:

cmd/cluster/testdata/TestNewKubeConfigCommandCmdGoldenOutput/cluster-get-kubeconfig-cmd-with-help.golden

@@ -1,18 +1,21 @@
-Retrieve cluster kubeconfig and print it to stdout
+Retrieves kubeconfig of the cluster and prints it to stdout.
+
 If you specify clusterName, kubeconfig will have a CurrentContext set to clusterName and
-will have this context defined
+will have its context defined.
+
 If you don't specify clusterName, kubeconfig will have multiple contexts for every cluster
-in the airship site. Context names will correspond to cluster names. CurrentContext will be empty
+in the airship site. Context names will correspond to cluster names. CurrentContext will be empty.
 
 Usage:
-  get-kubeconfig [clusterName] [flags]
+  get-kubeconfig CLUSTER_NAME [flags]
 
 Examples:
-# Retrieve target-cluster kubeconfig
-airshipctl cluster get-kubeconfig target-cluster
 
-# Retrieve kubeconfig for the entire site; the kubeconfig will have context for every cluster
-airshipctl cluster get-kubeconfig
+Retrieve target-cluster kubeconfig
+# airshipctl cluster get-kubeconfig target-cluster
+
+Retrieve kubeconfig for the entire site; the kubeconfig will have context for every cluster
+# airshipctl cluster get-kubeconfig
 
 
 Flags:

cmd/cluster/testdata/TestNewListCommandGoldenOutput/cluster-list-cmd-with-help.golden

@@ -1,15 +1,17 @@
-Retrieve the list of defined clusters
+
+Retrieve and list the defined clusters in the table form or display just the name as specified.
 
 Usage:
   list [flags]
 
 Examples:
-# Retrieve cluster list
-airshipctl cluster list --airshipconf /tmp/airconfig
-airshipctl cluster list -o table
-airshipctl cluster list -o name
+
+Retrieve list of clusters
+# airshipctl cluster list --airshipconf /tmp/airconfig
+# airshipctl cluster list -o table
+# airshipctl cluster list -o name
 
 
 Flags:
   -h, --help            help for list
-  -o, --output string   'table' and 'name' are available output formats (default "name")
+  -o, --output string   output formats. Supported options are 'table' and 'name' (default "name")

cmd/testdata/TestRootGoldenOutput/rootCmd-with-default-subcommands.golden

@@ -5,7 +5,7 @@ Usage:
 
 Available Commands:
   baremetal   Airshipctl command to manage bare metal host(s)
-  cluster     Manage Kubernetes clusters
+  cluster     Airshipctl command to manage kubernetes clusters
   completion  Generate completion script for the specified shell (bash or zsh)
   config      Manage the airshipctl config file
   document    Manage deployment documents