Auto generate cli docs

.gitignore

@@ -16,6 +16,9 @@ __debug_bin
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
 
+# ./cmd/docs output
+docs
+
 # Dependency directories (remove the comment below to include it)
 # vendor/
 

activity/activity.go

@@ -9,37 +9,38 @@ func NewActivityCommands() []*cli.Command {
 	return []*cli.Command{
 		{
 			Name:  "complete",
-			Usage: "Complete an activity",
+			Usage: common.CompleteActivityDefinition,
+			UsageText: common.CompleteActivityUsageText,
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:     common.FlagWorkflowID,
 					Aliases:  common.FlagWorkflowIDAlias,
-					Usage:    "Workflow Id",
+					Usage:    common.FlagWorkflowIDDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagRunID,
 					Aliases:  common.FlagRunIDAlias,
-					Usage:    "Run Id",
+					Usage:    common.FlagRunIDDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagActivityID,
-					Usage:    "The Activity Id to complete",
+					Usage:    common.FlagActivityCompleteDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagResult,
-					Usage:    "Set the result value of completion",
+					Usage:    common.FlagResultDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagIdentity,
-					Usage:    "Specify operator's identity",
+					Usage:    common.FlagIdentityDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
@@ -50,43 +51,44 @@ func NewActivityCommands() []*cli.Command {
 		},
 		{
 			Name:  "fail",
-			Usage: "Fail an activity",
+			Usage: common.FailActivityDefinition,
+			UsageText: common.FailActivityUsageText,
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:     common.FlagWorkflowID,
 					Aliases:  common.FlagWorkflowIDAlias,
-					Usage:    "Workflow Id",
+					Usage:    common.FlagWorkflowIDDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagRunID,
 					Aliases:  common.FlagRunIDAlias,
-					Usage:    "Run Id",
+					Usage:    common.FlagRunIDDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagActivityID,
-					Usage:    "The Activity Id to fail",
+					Usage:    common.FlagActivityFailDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagReason,
-					Usage:    "Reason to fail the Activity",
+					Usage:    common.FlagReasonDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagDetail,
-					Usage:    "Detail to fail the Activity",
+					Usage:    common.FlagDetailDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagIdentity,
-					Usage:    "Specify operator's identity",
+					Usage:    common.FlagIdentityDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},

app/app.go

@@ -88,7 +88,7 @@ func serverCommands(defaultCfg *sconfig.Config) []*cli.Command {
 	return []*cli.Command{
 		{
 			Name:        "server",
-			Usage:       "Commands for managing Temporal server",
+			Usage:       "Commands for managing the Temporal Server.",
 			Subcommands: server.NewServerCommands(defaultCfg),
 		},
 	}
@@ -97,62 +97,64 @@ func serverCommands(defaultCfg *sconfig.Config) []*cli.Command {
 var clientCommands = []*cli.Command{
 	{
 		Name:        "workflow",
-		Usage:       "Operations on Workflows",
+		Usage:       common.WorkflowDefinition,
 		Subcommands: workflow.NewWorkflowCommands(),
 	},
 	{
 		Name:        "activity",
-		Usage:       "Operations on Activities of Workflows",
+		Usage:       common.ActivityDefinition,
 		Subcommands: activity.NewActivityCommands(),
 	},
 	{
 		Name:        "task-queue",
-		Usage:       "Operations on Task Queues",
+		Usage:       common.TaskQueueDefinition,
 		Subcommands: taskqueue.NewTaskQueueCommands(),
 	},
 	{
 		Name:        "schedule",
-		Usage:       "Operations on Schedules",
+		Usage:       common.ScheduleDefinition,
+		UsageText: common.ScheduleUsageText,
 		Subcommands: schedule.NewScheduleCommands(),
 	},
-
 	{
 		Name:        "batch",
-		Usage:       "Operations on Batch jobs. Use workflow commands with --query flag to start batch jobs",
+		Usage:       common.BatchDefinition,
+		UsageText:   common.BatchUsageText,
 		Subcommands: batch.NewBatchCommands(),
 	},
 	{
 		Name:  "operator",
-		Usage: "Operation on Temporal server",
+		Usage: common.OperatorDefinition,
+		UsageText: common.OperatorUsageText,
 		Subcommands: []*cli.Command{
 			{
 				Name:        "namespace",
-				Usage:       "Operations on namespaces",
+				Usage:       common.NamespaceDefinition,
 				Subcommands: namespace.NewNamespaceCommands(),
 			},
 			{
 				Name:        "search-attribute",
-				Usage:       "Operations on search attributes",
+				Usage:       common.SearchAttributeDefinition,
 				Subcommands: searchattribute.NewSearchAttributeCommands(),
 			},
 			{
 				Name:        "cluster",
-				Usage:       "Operations on a Temporal cluster",
+				Usage:       common.ClusterDefinition,
 				Subcommands: cluster.NewClusterCommands(),
 			},
 		},
 	},
 	{
 		Name:        "env",
-		Usage:       "Manage client environment configurations",
+		Usage:       common.EnvDefinition,
 		Subcommands: env.NewEnvCommands(),
 	},
 }
 
 var completionCommands = []*cli.Command{
 	{
 		Name:        "completion",
-		Usage:       "Output shell completion code for the specified shell (zsh, bash)",
+		Usage:       "Output shell completion code for the specified shell (zsh, bash).",
 		Subcommands: completion.NewCompletionCommands(),
 	},
 }

batch/batch.go

@@ -9,11 +9,12 @@ func NewBatchCommands() []*cli.Command {
 	return []*cli.Command{
 		{
 			Name:  "describe",
-			Usage: "Describe a batch operation job",
+			Usage: common.DescribeBatchJobDefinition,
+			UsageText: common.DescribeBatchUsageText,
 			Flags: append([]cli.Flag{
 				&cli.StringFlag{
 					Name:     common.FlagJobID,
-					Usage:    "Batch Job Id",
+					Usage:    common.FlagJobIDDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
@@ -24,7 +25,8 @@ func NewBatchCommands() []*cli.Command {
 		},
 		{
 			Name:      "list",
-			Usage:     "List batch operation jobs",
+			Usage:     common.ListBatchJobsDefinition,
+			UsageText: common.ListBatchUsageText,
 			Flags:     common.FlagsForPaginationAndRendering,
 			ArgsUsage: " ",
 			Action: func(c *cli.Context) error {
@@ -33,17 +35,18 @@ func NewBatchCommands() []*cli.Command {
 		},
 		{
 			Name:  "terminate",
-			Usage: "Stop a batch operation job",
+			Usage: common.TerminateBatchJobDefinition,
+			UsageText: common.TerminateBatchUsageText,
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:     common.FlagJobID,
-					Usage:    "Batch Job Id",
+					Usage:    common.FlagJobIDDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},
 				&cli.StringFlag{
 					Name:     common.FlagReason,
-					Usage:    "Reason to stop the batch job",
+					Usage:    common.FlagReasonBatchDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},

cluster/cluster.go

@@ -10,14 +10,16 @@ func NewClusterCommands() []*cli.Command {
 	return []*cli.Command{
 		{
 			Name:  "health",
-			Usage: "Check health of frontend service",
+			Usage: common.HealthDefinition,
+			UsageText: common.HealthUsageText,
 			Action: func(c *cli.Context) error {
 				return HealthCheck(c)
 			},
 		},
 		{
 			Name:      "describe",
-			Usage:     "Show information about the cluster",
+			Usage:     common.DescribeDefinition,
+			UsageText: common.ClusterDescribeUsageText,
 			ArgsUsage: " ",
 			Flags: []cli.Flag{
 				&cli.StringFlag{
@@ -29,7 +31,7 @@ func NewClusterCommands() []*cli.Command {
 				},
 				&cli.StringFlag{
 					Name:     output.FlagFields,
-					Usage:    "customize fields to print. Set to 'long' to automatically print more of main fields",
+					Usage:    common.FlagFieldsDefinition,
 					Category: common.CategoryDisplay,
 				},
 			},
@@ -39,7 +41,8 @@ func NewClusterCommands() []*cli.Command {
 		},
 		{
 			Name:      "system",
-			Usage:     "Show information about the system and capabilities",
+			Usage:     common.SystemDefinition,
+			UsageText: common.ClusterSystemUsageText,
 			ArgsUsage: " ",
 			Flags: []cli.Flag{
 				&cli.StringFlag{
@@ -51,7 +54,7 @@ func NewClusterCommands() []*cli.Command {
 				},
 				&cli.StringFlag{
 					Name:     output.FlagFields,
-					Usage:    "customize fields to print. Set to 'long' to automatically print more of main fields",
+					Usage:    common.FlagFieldsDefinition,
 					Category: common.CategoryDisplay,
 				},
 			},
@@ -61,17 +64,18 @@ func NewClusterCommands() []*cli.Command {
 		},
 		{
 			Name:      "upsert",
-			Usage:     "Add or update a remote cluster",
+			Usage:     common.UpsertDefinition,
+			UsageText: common.ClusterUpsertUsageText,
 			ArgsUsage: " ",
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:     common.FlagClusterAddress,
-					Usage:    "Frontend address of the remote cluster",
+					Usage:    common.FlagClusterAddressDefinition,
 					Category: common.CategoryMain,
 				},
 				&cli.BoolFlag{
 					Name:     common.FlagClusterEnableConnection,
-					Usage:    "Enable cross cluster connection",
+					Usage:    common.FlagClusterEnableConnectionDefinition,
 					Category: common.CategoryMain,
 				},
 			},
@@ -81,7 +85,8 @@ func NewClusterCommands() []*cli.Command {
 		},
 		{
 			Name:      "list",
-			Usage:     "List all remote clusters",
+			Usage:     common.ListDefinition,
+			UsageText: common.ClusterListUsageText,
 			ArgsUsage: " ",
 			Flags:     common.FlagsForPaginationAndRendering,
 			Action: func(c *cli.Context) error {
@@ -90,12 +95,13 @@ func NewClusterCommands() []*cli.Command {
 		},
 		{
 			Name:      "remove",
-			Usage:     "Remove a remote cluster",
+			Usage:     common.RemoveDefinition,
+			UsageText: common.ClusterRemoveUsageText,
 			ArgsUsage: " ",
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:     common.FlagName,
-					Usage:    "Frontend address of the remote cluster",
+					Usage:    common.FlagNameDefinition,
 					Required: true,
 					Category: common.CategoryMain,
 				},