airship/airshipctl
Code Issues Proposed changes

Plan,Secret- updating cmd files for documentation

Browse Source 
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: I5d46bd361088cc1e4aff79a3009cd43a73ca1252
This commit is contained in:
Sirisha Gopigiri 2021-05-06 15:17:54 +05:30
parent 4c3140be93
commit 14ef1f8680
22 changed files with 157 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
cmd/plan/list.go
View File

@ -23,17 +23,18 @@ import (
const (
listLong = `
List life-cycle plans which were defined in document model.
List plans defined in site manifest.
`
listExample = `
#list plan
airshipctl plan list
List plan
# airshipctl plan list
#list plan(yaml output format)
airshipctl plan list -o yaml
List plan(yaml output format)
# airshipctl plan list -o yaml
#list plan(table output format)
airshipctl plan list -o table`
List plan(table output format)
# airshipctl plan list -o table`
)
// NewListCommand creates a command which prints available phase plans
@ -42,7 +43,7 @@ func NewListCommand(cfgFactory config.Factory) *cobra.Command {
listCmd := &cobra.Command{
Use: "list",
Short: "List plans",
Short: "Airshipctl command to list plans",
Long: listLong[1:],
Example: listExample,
RunE: func(cmd *cobra.Command, args []string) error {
@ -51,9 +52,7 @@ func NewListCommand(cfgFactory config.Factory) *cobra.Command {
},
}
flags := listCmd.Flags()
flags.StringVarP(&p.Options.FormatType,
"output", "o", "table", "'table' "+
"and 'yaml' are available "+
"output formats")
flags.StringVarP(&p.Options.FormatType, "output", "o", "table",
"output format. Supported formats are 'table' and 'yaml'")
return listCmd
}

5
cmd/plan/plan.go
View File

@ -22,8 +22,7 @@ import (
const (
planLong = `
This command provides capabilities for interacting with plan objects,
responsible for execution phases in groups
Provides capabilities for interacting with plan objects, responsible for execution of phases in groups.
`
)
@ -31,7 +30,7 @@ responsible for execution phases in groups
func NewPlanCommand(cfgFactory config.Factory) *cobra.Command {
planRootCmd := &cobra.Command{
Use: "plan",
Short: "Manage plans",
Short: "Airshipctl command to manage plans",
Long: planLong[1:],
}

31
cmd/plan/run.go
View File

@ -23,7 +23,15 @@ import (
const (
runLong = `
Run life-cycle phase plan which was defined in document model.
Run a plan defined in the site manifest. Specify the plan using the mandatory parameter PLAN_NAME.
To get list of plans associated for a site, run 'airshipctl plan list'.
`
runExample = `
Run plan named iso
# airshipctl plan run iso
Perform a dry run of a plan
# airshipctl plan run iso --dry-run
`
)
@ -34,10 +42,11 @@ func NewRunCommand(cfgFactory config.Factory) *cobra.Command {
Options: phase.PlanRunFlags{},
}
runCmd := &cobra.Command{
Use: "run PLAN_NAME",
Short: "Run plan",
Long: runLong[1:],
Args: cobra.ExactArgs(1),
Use: "run PLAN_NAME",
Short: "Airshipctl command to run plan",
Long: runLong[1:],
Example: runExample,
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
r.Options.PlanID.Name = args[0]
return r.RunE()
@ -45,15 +54,7 @@ func NewRunCommand(cfgFactory config.Factory) *cobra.Command {
}
flags := runCmd.Flags()
flags.BoolVar(
&r.Options.DryRun,
"dry-run",
false,
"simulate phase execution")
flags.DurationVar(
&r.Options.Timeout,
"wait-timeout",
0,
"wait timeout")
flags.BoolVar(&r.Options.DryRun, "dry-run", false, "simulate phase execution")
flags.DurationVar(&r.Options.Timeout, "wait-timeout", 0, "wait timeout")
return runCmd
}

16
cmd/plan/testdata/TestNewListCommandGoldenOutput/plan-list-cmd-with-help.golden vendored
View File

@ -1,19 +1,19 @@
List life-cycle plans which were defined in document model.
List plans defined in site manifest.
Usage:
list [flags]
Examples:
#list plan
airshipctl plan list
List plan
# airshipctl plan list
#list plan(yaml output format)
airshipctl plan list -o yaml
List plan(yaml output format)
# airshipctl plan list -o yaml
#list plan(table output format)
airshipctl plan list -o table
List plan(table output format)
# airshipctl plan list -o table
Flags:
-h, --help help for list
-o, --output string 'table' and 'yaml' are available output formats (default "table")
-o, --output string output format. Supported formats are 'table' and 'yaml' (default "table")

9
cmd/plan/testdata/TestNewPlanCommandGoldenOutput/plan-cmd-with-help.golden vendored
View File

@ -1,14 +1,13 @@
This command provides capabilities for interacting with plan objects,
responsible for execution phases in groups
Provides capabilities for interacting with plan objects, responsible for execution of phases in groups.
Usage:
plan [command]
Available Commands:
help Help about any command
list List plans
run Run plan
validate Validate plan
list Airshipctl command to list plans
run Airshipctl command to run plan
validate Airshipctl command to validate plan
Flags:
-h, --help help for plan

12
cmd/plan/testdata/TestNewRunCommandGoldenOutput/plan-run-with-help.golden vendored
View File

@ -1,8 +1,18 @@
Run life-cycle phase plan which was defined in document model.
Run a plan defined in the site manifest. Specify the plan using the mandatory parameter PLAN_NAME.
To get list of plans associated for a site, run 'airshipctl plan list'.
Usage:
run PLAN_NAME [flags]
Examples:
Run plan named iso
# airshipctl plan run iso
Perform a dry run of a plan
# airshipctl plan run iso --dry-run
Flags:
--dry-run simulate phase execution
-h, --help help for run

9
cmd/plan/testdata/TestNewValidateCommandGoldenOutput/plan-validate-with-help.golden vendored
View File

@ -1,7 +1,14 @@
Run life-cycle phase validation which was defined in document model.
Validate a plan defined in the site manifest. Specify the plan using the mandatory parameter PLAN_NAME.
To get list of plans associated for a site, run 'airshipctl plan list'.
Usage:
validate PLAN_NAME [flags]
Examples:
Validate plan named iso
# airshipctl plan validate iso
Flags:
-h, --help help for validate

17
cmd/plan/validate.go
View File

@ -23,7 +23,13 @@ import (
const (
validateLong = `
Run life-cycle phase validation which was defined in document model.
Validate a plan defined in the site manifest. Specify the plan using the mandatory parameter PLAN_NAME.
To get list of plans associated for a site, run 'airshipctl plan list'.
`
validateExample = `
Validate plan named iso
# airshipctl plan validate iso
`
)
@ -34,10 +40,11 @@ func NewValidateCommand(cfgFactory config.Factory) *cobra.Command {
Options: phase.PlanValidateFlags{},
}
runCmd := &cobra.Command{
Use: "validate PLAN_NAME",
Short: "Validate plan",
Long: validateLong[1:],
Args: cobra.ExactArgs(1),
Use: "validate PLAN_NAME",
Short: "Airshipctl command to validate plan",
Long: validateLong[1:],
Example: validateExample,
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
r.Options.PlanID.Name = args[0]
return r.RunE()

18
cmd/secret/generate/encryptionkey/encryptionkey.go
View File

@ -31,12 +31,11 @@ If regex arguments are passed the encryption key created would match the regular
`
cmdExample = `
# Generates a secure encryption key or passphrase.
airshipctl secret generate encryptionkey
Generates a secure encryption key or passphrase.
# airshipctl secret generate encryptionkey
# Generates a secure encryption key or passphrase matching the regular expression
airshipctl secret generate encryptionkey \
--regex Xy[a-c][0-9]!a*
Generates a secure encryption key or passphrase matching the regular expression
# airshipctl secret generate encryptionkey --regex Xy[a-c][0-9]!a*
`
)
@ -47,7 +46,7 @@ func NewGenerateEncryptionKeyCommand() *cobra.Command {
encryptionKeyCmd := &cobra.Command{
Use: "encryptionkey",
Short: "Generates a secure encryption key or passphrase",
Short: "Airshipctl command to generate a secure encryption key or passphrase",
Long: cmdLong[1:],
Example: cmdExample,
RunE: func(cmd *cobra.Command, args []string) error {
@ -64,10 +63,7 @@ func NewGenerateEncryptionKeyCommand() *cobra.Command {
},
}
encryptionKeyCmd.Flags().StringVar(&regex, "regex", "",
"Regular expression string")
encryptionKeyCmd.Flags().IntVar(&limit, "limit", 5,
"Limit number of characters for + or * regex")
encryptionKeyCmd.Flags().StringVar(&regex, "regex", "", "regular expression string")
encryptionKeyCmd.Flags().IntVar(&limit, "limit", 5, "limit number of characters for + or * regex")
return encryptionKeyCmd
}

13
cmd/secret/generate/encryptionkey/testdata/TestGenerateEncryptionKeyGoldenOutput/generate-encryptionkey-cmd-error.golden vendored
View File

@ -4,16 +4,15 @@ Usage:
Examples:
# Generates a secure encryption key or passphrase.
airshipctl secret generate encryptionkey
Generates a secure encryption key or passphrase.
# airshipctl secret generate encryptionkey
# Generates a secure encryption key or passphrase matching the regular expression
airshipctl secret generate encryptionkey \
--regex Xy[a-c][0-9]!a*
Generates a secure encryption key or passphrase matching the regular expression
# airshipctl secret generate encryptionkey --regex Xy[a-c][0-9]!a*
Flags:
-h, --help help for encryptionkey
--limit int Limit number of characters for + or * regex (default 5)
--regex string Regular expression string
--limit int limit number of characters for + or * regex (default 5)
--regex string regular expression string

13
cmd/secret/generate/encryptionkey/testdata/TestGenerateEncryptionKeyGoldenOutput/generate-encryptionkey-cmd-with-help.golden vendored
View File

@ -7,15 +7,14 @@ Usage:
Examples:
# Generates a secure encryption key or passphrase.
airshipctl secret generate encryptionkey
Generates a secure encryption key or passphrase.
# airshipctl secret generate encryptionkey
# Generates a secure encryption key or passphrase matching the regular expression
airshipctl secret generate encryptionkey \
--regex Xy[a-c][0-9]!a*
Generates a secure encryption key or passphrase matching the regular expression
# airshipctl secret generate encryptionkey --regex Xy[a-c][0-9]!a*
Flags:
-h, --help help for encryptionkey
--limit int Limit number of characters for + or * regex (default 5)
--regex string Regular expression string
--limit int limit number of characters for + or * regex (default 5)
--regex string regular expression string

2
cmd/secret/generate/generate.go
View File

@ -25,7 +25,7 @@ func NewGenerateCommand() *cobra.Command {
generateRootCmd := &cobra.Command{
Use: "generate",
// TODO(howell): Make this more expressive
Short: "Generate various secrets",
Short: "Airshipctl command to generate secrets",
}
generateRootCmd.AddCommand(encryptionkey.NewGenerateEncryptionKeyCommand())

3
cmd/secret/secret.go
View File

@ -25,7 +25,8 @@ func NewSecretCommand() *cobra.Command {
secretRootCmd := &cobra.Command{
Use: "secret",
// TODO(howell): Make this more expressive
Short: "Manage secrets",
Short: "Airshipctl command to manage secrets",
Long: "Commands and sub-commnads defined can be used to manage secrets.",
}
secretRootCmd.AddCommand(generate.NewGenerateCommand())

4
cmd/testdata/TestRootGoldenOutput/rootCmd-with-default-subcommands.golden vendored
View File

@ -13,8 +13,8 @@ Available Commands:
document Manage deployment documents
help Help about any command
phase Airshipctl command to manage phases
plan Manage plans
secret Manage secrets
plan Airshipctl command to manage plans
secret Airshipctl command to manage secrets
version Show the version number of airshipctl
Flags:

4
docs/source/cli/airshipctl.md
View File

@ -25,7 +25,7 @@ A unified entrypoint to various airship components
* [airshipctl config](airshipctl_config.md) - Airshipctl command to manage airshipctl config file
* [airshipctl document](airshipctl_document.md) - Manage deployment documents
* [airshipctl phase](airshipctl_phase.md) - Airshipctl command to manage phases
* [airshipctl plan](airshipctl_plan.md) - Manage plans
* [airshipctl secret](airshipctl_secret.md) - Manage secrets
* [airshipctl plan](airshipctl_plan.md) - Airshipctl command to manage plans
* [airshipctl secret](airshipctl_secret.md) - Airshipctl command to manage secrets
* [airshipctl version](airshipctl_version.md) - Show the version number of airshipctl

11
docs/source/cli/airshipctl_plan.md
View File

@ -1,11 +1,10 @@
## airshipctl plan
Manage plans
Airshipctl command to manage plans
### Synopsis
This command provides capabilities for interacting with plan objects,
responsible for execution phases in groups
Provides capabilities for interacting with plan objects, responsible for execution of phases in groups.
### Options
@ -24,7 +23,7 @@ responsible for execution phases in groups
### SEE ALSO
* [airshipctl](airshipctl.md) - A unified entrypoint to various airship components
* [airshipctl plan list](airshipctl_plan_list.md) - List plans
* [airshipctl plan run](airshipctl_plan_run.md) - Run plan
* [airshipctl plan validate](airshipctl_plan_validate.md) - Validate plan
* [airshipctl plan list](airshipctl_plan_list.md) - Airshipctl command to list plans
* [airshipctl plan run](airshipctl_plan_run.md) - Airshipctl command to run plan
* [airshipctl plan validate](airshipctl_plan_validate.md) - Airshipctl command to validate plan

20
docs/source/cli/airshipctl_plan_list.md
View File

@ -1,10 +1,10 @@
## airshipctl plan list
List plans
Airshipctl command to list plans
### Synopsis
List life-cycle plans which were defined in document model.
List plans defined in site manifest.
```
@ -15,21 +15,21 @@ airshipctl plan list [flags]
```
#list plan
airshipctl plan list
List plan
# airshipctl plan list
#list plan(yaml output format)
airshipctl plan list -o yaml
List plan(yaml output format)
# airshipctl plan list -o yaml
#list plan(table output format)
airshipctl plan list -o table
List plan(table output format)
# airshipctl plan list -o table
```
### Options
```
-h, --help help for list
-o, --output string 'table' and 'yaml' are available output formats (default "table")
-o, --output string output format. Supported formats are 'table' and 'yaml' (default "table")
```
### Options inherited from parent commands
@ -41,5 +41,5 @@ airshipctl plan list -o table
### SEE ALSO
* [airshipctl plan](airshipctl_plan.md) - Manage plans
* [airshipctl plan](airshipctl_plan.md) - Airshipctl command to manage plans

19
docs/source/cli/airshipctl_plan_run.md
View File

@ -1,16 +1,29 @@
## airshipctl plan run
Run plan
Airshipctl command to run plan
### Synopsis
Run life-cycle phase plan which was defined in document model.
Run a plan defined in the site manifest. Specify the plan using the mandatory parameter PLAN_NAME.
To get list of plans associated for a site, run 'airshipctl plan list'.
```
airshipctl plan run PLAN_NAME [flags]
```
### Examples
```
Run plan named iso
# airshipctl plan run iso
Perform a dry run of a plan
# airshipctl plan run iso --dry-run
```
### Options
```
@ -28,5 +41,5 @@ airshipctl plan run PLAN_NAME [flags]
### SEE ALSO
* [airshipctl plan](airshipctl_plan.md) - Manage plans
* [airshipctl plan](airshipctl_plan.md) - Airshipctl command to manage plans

16
docs/source/cli/airshipctl_plan_validate.md
View File

@ -1,16 +1,26 @@
## airshipctl plan validate
Validate plan
Airshipctl command to validate plan
### Synopsis
Run life-cycle phase validation which was defined in document model.
Validate a plan defined in the site manifest. Specify the plan using the mandatory parameter PLAN_NAME.
To get list of plans associated for a site, run 'airshipctl plan list'.
```
airshipctl plan validate PLAN_NAME [flags]
```
### Examples
```
Validate plan named iso
# airshipctl plan validate iso
```
### Options
```
@ -26,5 +36,5 @@ airshipctl plan validate PLAN_NAME [flags]
### SEE ALSO
* [airshipctl plan](airshipctl_plan.md) - Manage plans
* [airshipctl plan](airshipctl_plan.md) - Airshipctl command to manage plans

6
docs/source/cli/airshipctl_secret.md
View File

@ -1,10 +1,10 @@
## airshipctl secret
Manage secrets
Airshipctl command to manage secrets
### Synopsis
Manage secrets
Commands and sub-commnads defined can be used to manage secrets.
### Options
@ -22,5 +22,5 @@ Manage secrets
### SEE ALSO
* [airshipctl](airshipctl.md) - A unified entrypoint to various airship components
* [airshipctl secret generate](airshipctl_secret_generate.md) - Generate various secrets
* [airshipctl secret generate](airshipctl_secret_generate.md) - Airshipctl command to generate secrets

8
docs/source/cli/airshipctl_secret_generate.md
View File

@ -1,10 +1,10 @@
## airshipctl secret generate
Generate various secrets
Airshipctl command to generate secrets
### Synopsis
Generate various secrets
Airshipctl command to generate secrets
### Options
@ -21,6 +21,6 @@ Generate various secrets
### SEE ALSO
* [airshipctl secret](airshipctl_secret.md) - Manage secrets
* [airshipctl secret generate encryptionkey](airshipctl_secret_generate_encryptionkey.md) - Generates a secure encryption key or passphrase
* [airshipctl secret](airshipctl_secret.md) - Airshipctl command to manage secrets
* [airshipctl secret generate encryptionkey](airshipctl_secret_generate_encryptionkey.md) - Airshipctl command to generate a secure encryption key or passphrase

17
docs/source/cli/airshipctl_secret_generate_encryptionkey.md
View File

@ -1,6 +1,6 @@
## airshipctl secret generate encryptionkey
Generates a secure encryption key or passphrase
Airshipctl command to generate a secure encryption key or passphrase
### Synopsis
@ -17,12 +17,11 @@ airshipctl secret generate encryptionkey [flags]
```
# Generates a secure encryption key or passphrase.
airshipctl secret generate encryptionkey
Generates a secure encryption key or passphrase.
# airshipctl secret generate encryptionkey
# Generates a secure encryption key or passphrase matching the regular expression
airshipctl secret generate encryptionkey \
--regex Xy[a-c][0-9]!a*
Generates a secure encryption key or passphrase matching the regular expression
# airshipctl secret generate encryptionkey --regex Xy[a-c][0-9]!a*
```
@ -30,8 +29,8 @@ airshipctl secret generate encryptionkey \
```
-h, --help help for encryptionkey
--limit int Limit number of characters for + or * regex (default 5)
--regex string Regular expression string
--limit int limit number of characters for + or * regex (default 5)
--regex string regular expression string
```
### Options inherited from parent commands
@ -43,5 +42,5 @@ airshipctl secret generate encryptionkey \
### SEE ALSO
* [airshipctl secret generate](airshipctl_secret_generate.md) - Generate various secrets
* [airshipctl secret generate](airshipctl_secret_generate.md) - Airshipctl command to generate secrets