Phase- 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: I3587ad211f7d614b5cc6a162ca352ac54c3b90f0

cmd/phase/list.go

@@ -23,25 +23,24 @@ import (
 
 const (
 	cmdLong = `
-List life-cycle phases which were defined in document model by group.
-Phases within a group are executed sequentially. Multiple phase groups
-are executed in parallel.
+List phases defined in site manifests by plan. Phases within a plan are
+executed sequentially. Multiple phase plans are executed in parallel.
 `
 	listExample = `
-# List phases of phasePlan
-airshipctl phase list --plan phasePlan
+List phases of phasePlan
+# airshipctl phase list --plan phasePlan
 
-# To output the contents to table (default operation)
-airshipctl phase list --plan phasePlan -o table
+To output the contents in table format (default operation)
+# airshipctl phase list --plan phasePlan -o table
 
-# To output the contents to yaml
-airshipctl phase list --plan phasePlan -o yaml
+To output the contents in yaml format
+# airshipctl phase list --plan phasePlan -o yaml
 
-# List all phases
-airshipctl phase list
+List all phases
+# airshipctl phase list
 
-# List phases with clustername
-airshipctl phase list --cluster-name clustername
+List phases with clustername
+# airshipctl phase list --cluster-name clustername
 `
 )
 
@@ -51,7 +50,7 @@ func NewListCommand(cfgFactory config.Factory) *cobra.Command {
 
 	planCmd := &cobra.Command{
 		Use:     "list PHASE_NAME",
-		Short:   "List phases",
+		Short:   "Airshipctl command to list phases",
 		Long:    cmdLong[1:],
 		Example: listExample,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -67,22 +66,8 @@ func NewListCommand(cfgFactory config.Factory) *cobra.Command {
 func addListFlags(options *phase.ListCommand, cmd *cobra.Command) {
 	flags := cmd.Flags()
 
-	flags.StringVarP(
-		&options.ClusterName,
-		"cluster-name",
-		"c",
-		"",
-		"filter documents by cluster name")
-
-	flags.StringVar(
-		&options.PlanID.Name,
-		"plan",
-		"",
-		"Plan name of a plan")
-
-	flags.StringVarP(
-		&options.OutputFormat,
-		"output", "o", "table", "'table' "+
-			"and 'yaml' are available "+
-			"output formats")
+	flags.StringVarP(&options.ClusterName, "cluster-name", "c", "", "filter documents by cluster name")
+	flags.StringVar(&options.PlanID.Name, "plan", "", "plan name of a plan")
+	flags.StringVarP(&options.OutputFormat, "output", "o", "table",
+		"output format. Supported formats are 'table' and 'yaml'")
 }

cmd/phase/phase.go

@@ -22,16 +22,15 @@ import (
 
 const (
 	phaseLong = `
-This command provides capabilities for interacting with phases,
-such as getting list and applying specific one.
+Provides capabilities for interacting with phases, such as getting list of phases or applying a specific one.
 `
 )
 
 // NewPhaseCommand creates a command for interacting with phases
 func NewPhaseCommand(cfgFactory config.Factory) *cobra.Command {
 	phaseRootCmd := &cobra.Command{
 		Use:   "phase",
-		Short: "Manage phases",
+		Short: "Airshipctl command to manage phases",
 		Long:  phaseLong[1:],
 	}
 

cmd/phase/render.go

@@ -22,20 +22,22 @@ import (
 )
 
 const (
+	renderLong = `
+Render documents for a phase.
+`
+
 	renderExample = `
-# Get all 'initinfra' phase documents containing labels "app=helm" and
-# "service=tiller"
-airshipctl phase render initinfra -l app=helm,service=tiller
+Get all 'initinfra' phase documents containing labels "app=helm" and "service=tiller"
+# airshipctl phase render initinfra -l app=helm,service=tiller
 
-# Get all phase documents containing labels "app=helm" and "service=tiller"
-# and kind 'Deployment'
-airshipctl phase render initinfra -l app=helm,service=tiller -k Deployment
+Get all phase documents containing labels "app=helm" and "service=tiller" and kind 'Deployment'
+# airshipctl phase render initinfra -l app=helm,service=tiller -k Deployment
 
-# Get all documents from config bundle
-airshipctl phase render --source config
+Get all documents from config bundle
+# airshipctl phase render --source config
 
-# Get all documents executor rendered documents for a phase
-airshipctl phase render initinfra --source executor
+Get all documents executor rendered documents for a phase
+# airshipctl phase render initinfra --source executor
 `
 )
 
@@ -44,7 +46,8 @@ func NewRenderCommand(cfgFactory config.Factory) *cobra.Command {
 	filterOptions := &phase.RenderCommand{}
 	renderCmd := &cobra.Command{
 		Use:     "render PHASE_NAME",
-		Short:   "Render phase documents from model",
+		Short:   "Airshipctl command to render phase documents from model",
+		Long:    renderLong,
 		Example: renderExample,
 		Args:    RenderArgs(filterOptions),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -60,48 +63,15 @@ func NewRenderCommand(cfgFactory config.Factory) *cobra.Command {
 func addRenderFlags(filterOptions *phase.RenderCommand, cmd *cobra.Command) {
 	flags := cmd.Flags()
 
-	flags.StringVarP(
-		&filterOptions.Label,
-		"label",
-		"l",
-		"",
-		"filter documents by Labels")
-
-	flags.StringVarP(
-		&filterOptions.Annotation,
-		"annotation",
-		"a",
-		"",
-		"filter documents by Annotations")
-
-	flags.StringVarP(
-		&filterOptions.APIVersion,
-		"apiversion",
-		"g",
-		"",
-		"filter documents by API version")
-
-	flags.StringVarP(
-		&filterOptions.Kind,
-		"kind",
-		"k",
-		"",
-		"filter documents by Kinds")
-
-	flags.StringVarP(
-		&filterOptions.Source,
-		"source",
-		"s",
-		phase.RenderSourcePhase,
-		"phase: phase entrypoint will be rendered by kustomize, if entrypoint is not specified "+
-			"error will be returned\n"+
+	flags.StringVarP(&filterOptions.Label, "label", "l", "", "filter documents by Labels")
+	flags.StringVarP(&filterOptions.Annotation, "annotation", "a", "", "filter documents by Annotations")
+	flags.StringVarP(&filterOptions.APIVersion, "apiversion", "g", "", "filter documents by API version")
+	flags.StringVarP(&filterOptions.Kind, "kind", "k", "", "filter documents by Kind")
+	flags.StringVarP(&filterOptions.Source, "source", "s", phase.RenderSourcePhase,
+		"phase: phase entrypoint will be rendered by kustomize, if entrypoint is not specified error will be returned\n"+
 			"executor: rendering will be performed by executor if the phase\n"+
 			"config: this will render bundle containing phase and executor documents")
-	flags.BoolVarP(
-		&filterOptions.FailOnDecryptionError,
-		"decrypt",
-		"d",
-		false,
+	flags.BoolVarP(&filterOptions.FailOnDecryptionError, "decrypt", "d", false,
 		"ensure that decryption of encrypted documents has finished successfully")
 }
 

cmd/phase/run.go

@@ -24,10 +24,13 @@ import (
 const (
 	// TODO (kkalynovskyi) when different phase executors will be implemented, and their description is more clear,
 	// add documentation here. also consider adding dynamic phase descriptions based on executors.
-	runLong    = `Run specific life-cycle phase such as ephemeral-control-plane, target-initinfra etc...`
+	runLong = `
+Run a phase such as controlplane-ephemeral, remotedirect-ephemeral, initinfra-ephemeral, etc...
+To list the phases associated with a site, run 'airshipctl phase list'.
+`
 	runExample = `
-# Run initinfra phase
-airshipctl phase run ephemeral-control-plane
+Run initinfra phase
+# airshipctl phase run ephemeral-control-plane
 `
 )
 
@@ -40,7 +43,7 @@ func NewRunCommand(cfgFactory config.Factory) *cobra.Command {
 
 	runCmd := &cobra.Command{
 		Use:     "run PHASE_NAME",
-		Short:   "Run phase",
+		Short:   "Airshipctl command to run phase",
 		Long:    runLong,
 		Args:    cobra.ExactArgs(1),
 		Example: runExample,
@@ -50,15 +53,7 @@ func NewRunCommand(cfgFactory config.Factory) *cobra.Command {
 		},
 	}
 	flags := runCmd.Flags()
-	flags.BoolVar(
-		&p.Options.DryRun,
-		"dry-run",
-		false,
-		"simulate phase execution")
-	flags.DurationVar(
-		&p.Options.Timeout,
-		"wait-timeout",
-		0,
-		"wait timeout")
+	flags.BoolVar(&p.Options.DryRun, "dry-run", false, "simulate phase execution")
+	flags.DurationVar(&p.Options.Timeout, "wait-timeout", 0, "wait timeout")
 	return runCmd
 }

cmd/phase/status.go

@@ -22,10 +22,13 @@ import (
 )
 
 const (
-	statusLong    = `Status of the specific life-cycle phase such as ephemeral-control-plane, target-initinfra etc...`
+	statusLong = `
+Get the status of a phase such as ephemeral-control-plane, target-initinfra etc...
+To list the phases associated with a site, run 'airshipctl phase list'.
+`
 	statusExample = `
-#Status of initinfra phase
-airshipctl phase status ephemeral-control-plane
+Status of initinfra phase
+# airshipctl phase status ephemeral-control-plane
 `
 )
 
@@ -37,8 +40,8 @@ func NewStatusCommand(cfgFactory config.Factory) *cobra.Command {
 	}
 
 	statusCmd := &cobra.Command{
-		Use:     "status",
-		Short:   "Status of the phase",
+		Use:     "status PHASE_NAME",
+		Short:   "Airshipctl command to show status of the phase",
 		Long:    statusLong,
 		Args:    cobra.ExactArgs(1),
 		Example: statusExample,

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

@@ -1,30 +1,29 @@
-List life-cycle phases which were defined in document model by group.
-Phases within a group are executed sequentially. Multiple phase groups
-are executed in parallel.
+List phases defined in site manifests by plan. Phases within a plan are
+executed sequentially. Multiple phase plans are executed in parallel.
 
 Usage:
   list PHASE_NAME [flags]
 
 Examples:
 
-# List phases of phasePlan
-airshipctl phase list --plan phasePlan
+List phases of phasePlan
+# airshipctl phase list --plan phasePlan
 
-# To output the contents to table (default operation)
-airshipctl phase list --plan phasePlan -o table
+To output the contents in table format (default operation)
+# airshipctl phase list --plan phasePlan -o table
 
-# To output the contents to yaml
-airshipctl phase list --plan phasePlan -o yaml
+To output the contents in yaml format
+# airshipctl phase list --plan phasePlan -o yaml
 
-# List all phases
-airshipctl phase list
+List all phases
+# airshipctl phase list
 
-# List phases with clustername
-airshipctl phase list --cluster-name clustername
+List phases with clustername
+# airshipctl phase list --cluster-name clustername
 
 
 Flags:
   -c, --cluster-name string   filter documents by cluster name
   -h, --help                  help for list
-  -o, --output string         'table' and 'yaml' are available output formats (default "table")
-      --plan string           Plan name of a plan
+  -o, --output string         output format. Supported formats are 'table' and 'yaml' (default "table")
+      --plan string           plan name of a plan

cmd/phase/testdata/TestNewPhaseCommandGoldenOutput/phase-cmd-with-help.golden

@@ -1,17 +1,16 @@
-This command provides capabilities for interacting with phases,
-such as getting list and applying specific one.
+Provides capabilities for interacting with phases, such as getting list of phases or applying a specific one.
 
 Usage:
   phase [command]
 
 Available Commands:
   help        Help about any command
-  list        List phases
-  render      Render phase documents from model
-  run         Run phase
-  status      Status of the phase
-  tree        Tree view of kustomize entrypoints of phase
-  validate    Assert that a phase is valid
+  list        Airshipctl command to list phases
+  render      Airshipctl command to render phase documents from model
+  run         Airshipctl command to run phase
+  status      Airshipctl command to show status of the phase
+  tree        Airshipctl command to show tree view of kustomize entrypoints of phase
+  validate    Airshipctl command to validate phase and its documents
 
 Flags:
   -h, --help   help for phase

cmd/phase/testdata/TestNewTreeCommandGoldenOutput/tree-cmd-with-help.golden

@@ -1,15 +1,15 @@
-Summarized tree view of the kustomize entrypoints of a specific phase
+Get tree view of the kustomize entrypoints of a phase.
 
 Usage:
   tree PHASE_NAME [flags]
 
 Examples:
 
-# yaml explorer of a phase with relative path
-airshipctl phase tree /manifests/site/test-site/ephemeral/initinfra
+yaml explorer of a phase with relative path
+# airshipctl phase tree /manifests/site/test-site/ephemeral/initinfra
 
-#yaml explorer of a phase with phase name
-airshipctl phase tree initinfra-ephemeral
+yaml explorer of a phase with phase name
+# airshipctl phase tree initinfra-ephemeral
 
 
 Flags:

cmd/phase/testdata/TestRenderGoldenOutput/render-with-help.golden

@@ -1,31 +1,30 @@
-Render phase documents from model
+
+Render documents for a phase.
 
 Usage:
   render PHASE_NAME [flags]
 
 Examples:
 
-# Get all 'initinfra' phase documents containing labels "app=helm" and
-# "service=tiller"
-airshipctl phase render initinfra -l app=helm,service=tiller
+Get all 'initinfra' phase documents containing labels "app=helm" and "service=tiller"
+# airshipctl phase render initinfra -l app=helm,service=tiller
 
-# Get all phase documents containing labels "app=helm" and "service=tiller"
-# and kind 'Deployment'
-airshipctl phase render initinfra -l app=helm,service=tiller -k Deployment
+Get all phase documents containing labels "app=helm" and "service=tiller" and kind 'Deployment'
+# airshipctl phase render initinfra -l app=helm,service=tiller -k Deployment
 
-# Get all documents from config bundle
-airshipctl phase render --source config
+Get all documents from config bundle
+# airshipctl phase render --source config
 
-# Get all documents executor rendered documents for a phase
-airshipctl phase render initinfra --source executor
+Get all documents executor rendered documents for a phase
+# airshipctl phase render initinfra --source executor
 
 
 Flags:
   -a, --annotation string   filter documents by Annotations
   -g, --apiversion string   filter documents by API version
   -d, --decrypt             ensure that decryption of encrypted documents has finished successfully
   -h, --help                help for render
-  -k, --kind string         filter documents by Kinds
+  -k, --kind string         filter documents by Kind
   -l, --label string        filter documents by Labels
   -s, --source string       phase: phase entrypoint will be rendered by kustomize, if entrypoint is not specified error will be returned
                             executor: rendering will be performed by executor if the phase