Autodoc generation for cobra commands (#29)

flytectl/README.md

@@ -15,6 +15,8 @@ Flytectl is designed to be a portable, lightweight, CLI for working with Flyte.
 ## Docs
 
 Docs are generated using Sphinx and are available at [flytectl.rtfd.io](https://flytectl.rtfd.io)
+Generating docs locally can be accomplished by running make gendocs from within the docs folder
+
 
 ## Installation
 
@@ -26,3 +28,4 @@ curl -s https://raw.githubusercontent.com/lyft/flytectl/master/install.sh | bash
 
 [Contribution guidelines for this project](docs/CONTRIBUTING.md)
 
+

flytectl/cmd/core/cmd.go

@@ -19,14 +19,17 @@ type CommandEntry struct {
 	ProjectDomainNotRequired bool
 	CmdFunc                  CommandFunc
 	Aliases                  []string
+	Short                    string
+	Long                     string
 	PFlagProvider            PFlagProvider
 }
 
 func AddCommands(rootCmd *cobra.Command, cmdFuncs map[string]CommandEntry) {
 	for resource, cmdEntry := range cmdFuncs {
 		cmd := &cobra.Command{
 			Use:     resource,
-			Short:   fmt.Sprintf("Retrieves %v resources.", resource),
+			Short:   cmdEntry.Short,
+			Long:    cmdEntry.Long,
 			Aliases: cmdEntry.Aliases,
 			RunE:    generateCommandFunc(cmdEntry),
 		}

flytectl/cmd/get/execution.go

@@ -13,6 +13,41 @@ import (
 	"github.com/lyft/flytectl/pkg/printer"
 )
 
+const(
+	executionShort = "Gets execution resources"
+	executionLong  = `
+Retrieves all the executions within project and domain.(execution,executions can be used interchangeably in these commands)
+::
+
+ bin/flytectl get execution -p flytesnacks -d development
+
+Retrieves execution by name within project and domain.
+
+::
+
+ bin/flytectl execution -p flytesnacks -d development oeh94k9r2r
+
+Retrieves execution by filters
+::
+
+ Not yet implemented
+
+Retrieves all the execution within project and domain in yaml format
+
+::
+
+ bin/flytectl get execution -p flytesnacks -d development -o yaml
+
+Retrieves all the execution within project and domain in json format.
+
+::
+
+ bin/flytectl get execution -p flytesnacks -d development -o json
+
+Usage
+`
+)
+
 var executionColumns = []printer.Column{
 	{"Name", "$.id.name"},
 	{"Workflow Name", "$.closure.workflowId.name"},

flytectl/cmd/get/get.go

@@ -6,19 +6,37 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// Long descriptions are whitespace sensitive when generating docs using sphinx.
+const (
+	getCmdShort = `Used for fetching various flyte resources including tasks/workflows/launchplans/executions/project.`
+	getCmdLong  = `
+Example get projects.
+::
+
+ bin/flytectl get project
+`
+)
+
 // CreateGetCommand will return get command
 func CreateGetCommand() *cobra.Command {
 	getCmd := &cobra.Command{
 		Use:   "get",
-		Short: "Retrieve various resource.",
+		Short: getCmdShort,
+		Long: getCmdLong,
 	}
 
 	getResourcesFuncs := map[string]cmdcore.CommandEntry{
-		"project":    {CmdFunc: getProjectsFunc, Aliases: []string{"projects"}, ProjectDomainNotRequired: true},
-		"task":       {CmdFunc: getTaskFunc, Aliases: []string{"tasks"}},
-		"workflow":   {CmdFunc: getWorkflowFunc, Aliases: []string{"workflows"}},
-		"launchplan": {CmdFunc: getLaunchPlanFunc, Aliases: []string{"launchplans"}},
-		"execution":  {CmdFunc: getExecutionFunc, Aliases: []string{"executions"}},
+		"project": {CmdFunc: getProjectsFunc, Aliases: []string{"projects"}, ProjectDomainNotRequired: true,
+			Short: projectShort,
+			Long:  projectLong},
+		"task": {CmdFunc: getTaskFunc, Aliases: []string{"tasks"}, Short: taskShort,
+			Long: taskLong},
+		"workflow": {CmdFunc: getWorkflowFunc, Aliases: []string{"workflows"}, Short: workflowShort,
+			Long: workflowLong},
+		"launchplan": {CmdFunc: getLaunchPlanFunc, Aliases: []string{"launchplans"}, Short: launchPlanShort,
+			Long: launchPlanLong},
+		"execution": {CmdFunc: getExecutionFunc, Aliases: []string{"executions"}, Short: executionShort,
+			Long: executionLong},
 	}
 
 	cmdcore.AddCommands(getCmd, getResourcesFuncs)

flytectl/cmd/get/launch_plan.go

@@ -11,6 +11,42 @@ import (
 	"github.com/lyft/flytestdlib/logger"
 )
 
+const(
+
+	launchPlanShort = "Gets launch plan resources"
+	launchPlanLong  = `
+Retrieves all the launch plans within project and domain.(launchplan,launchplans can be used interchangeably in these commands)
+::
+
+ bin/flytectl get launchplan -p flytesnacks -d development
+
+Retrieves launch plan by name within project and domain.
+
+::
+
+ bin/flytectl launchplan -p flytesnacks -d development recipes.core.basic.lp.my_wf
+
+Retrieves launchplan by filters.
+::
+
+ Not yet implemented
+
+Retrieves all the launchplan within project and domain in yaml format.
+
+::
+
+ bin/flytectl get launchplan -p flytesnacks -d development -o yaml
+
+Retrieves all the launchplan within project and domain in json format
+
+::
+
+ bin/flytectl get launchplan -p flytesnacks -d development -o json
+
+Usage
+`
+)
+
 var launchplanColumns = []printer.Column{
 	{"Version", "$.id.version"},
 	{"Name", "$.id.name"},

flytectl/cmd/get/project.go

@@ -12,6 +12,41 @@ import (
 	"github.com/lyft/flytectl/pkg/printer"
 )
 
+const(
+projectShort = "Gets project resources"
+projectLong  = `
+Retrieves all the projects.(project,projects can be used interchangeably in these commands)
+::
+
+ bin/flytectl get project
+
+Retrieves project by name
+
+::
+
+ bin/flytectl get project flytesnacks
+
+Retrieves project by filters
+::
+
+ Not yet implemented
+
+Retrieves all the projects in yaml format
+
+::
+
+ bin/flytectl get project -o yaml
+
+Retrieves all the projects in json format
+
+::
+
+ bin/flytectl get project -o json
+
+Usage
+`
+)
+
 var projectColumns = []printer.Column{
 	{"ID", "$.id"},
 	{"Name", "$.name"},

flytectl/cmd/get/task.go

@@ -14,6 +14,41 @@ import (
 	"github.com/lyft/flyteidl/gen/pb-go/flyteidl/admin"
 )
 
+const(
+	taskShort = "Gets task resources"
+	taskLong  = `
+Retrieves all the task within project and domain.(task,tasks can be used interchangeably in these commands)
+::
+
+ bin/flytectl get task -p flytesnacks -d development
+
+Retrieves task by name within project and domain.
+
+::
+
+ bin/flytectl task -p flytesnacks -d development square
+
+Retrieves project by filters.
+::
+
+ Not yet implemented
+
+Retrieves all the tasks within project and domain in yaml format.
+
+::
+
+ bin/flytectl get task -p flytesnacks -d development -o yaml
+
+Retrieves all the tasks within project and domain in json format.
+
+::
+
+ bin/flytectl get task -p flytesnacks -d development -o json
+
+Usage
+`
+)
+
 var taskColumns = []printer.Column{
 	{"Version", "$.id.version"},
 	{"Name", "$.id.name"},

flytectl/cmd/get/workflow.go

@@ -13,6 +13,41 @@ import (
 	"github.com/lyft/flyteidl/gen/pb-go/flyteidl/admin"
 )
 
+const(
+	workflowShort = "Gets workflow resources"
+	workflowLong  = `
+Retrieves all the workflows within project and domain.(workflow,workflows can be used interchangeably in these commands)
+::
+
+ bin/flytectl get workflow -p flytesnacks -d development
+
+Retrieves workflow by name within project and domain.
+
+::
+
+ bin/flytectl workflow -p flytesnacks -d development  recipes.plugins.k8s_spark.pyspark_pi.my_spark
+
+Retrieves workflow by filters. 
+::
+
+ Not yet implemented
+
+Retrieves all the workflow within project and domain in yaml format.
+
+::
+
+ bin/flytectl get workflow -p flytesnacks -d development -o yaml
+
+Retrieves all the workflow within project and domain in json format.
+
+::
+
+ bin/flytectl get workflow -p flytesnacks -d development -o json
+
+Usage
+`
+)
+
 var workflowColumns = []printer.Column{
 	{"Version", "$.id.version"},
 	{"Name", "$.id.name"},

flytectl/cmd/register/files.go

@@ -11,6 +11,42 @@ import (
 	"sort"
 )
 
+const(
+	registerFilesShort = "Registers file resources"
+	registerFilesLong  = `
+Registers all the serialized protobuf files including tasks, workflows and launchplans with default v1 version.
+If there are already registered entities with v1 version then the command will fail immediately on the first such encounter.
+::
+
+ bin/flytectl register file  _pb_output/* -d development  -p flytesnacks
+
+If you want to continue executing registration on other files ignoring the errors including version conflicts then pass in
+the skipOnError flag.
+
+::
+
+ bin/flytectl register file  _pb_output/* -d development  -p flytesnacks --skipOnError
+
+Using short format of skipOnError flag
+::
+
+ bin/flytectl register file  _pb_output/* -d development  -p flytesnacks -s
+
+Overriding the default version v1 using version string.
+::
+
+ bin/flytectl register file  _pb_output/* -d development  -p flytesnacks -v v2
+
+Change the o/p format has not effect on registration. The O/p is currently available only in table format.
+
+::
+
+ bin/flytectl register file  _pb_output/* -d development  -p flytesnacks -s -o yaml
+
+Usage
+`
+)
+
 func registerFromFilesFunc(ctx context.Context, args []string, cmdCtx cmdCore.CommandContext) error {
 	files := args
 	sort.Strings(files)

flytectl/cmd/register/register.go

@@ -5,18 +5,27 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// Long descriptions are whitespace sensitive when generating docs using sphinx.
+const (
+	registerCmdShort = "Registers tasks/workflows/launchplans from list of generated serialized files."
+	registercmdLong  = `
+Takes input files as serialized versions of the tasks/workflows/launchplans and registers them with flyteadmin.
+Currently these input files are protobuf files generated as output from flytekit serialize.
+Project & Domain are mandatory fields to be passed for registration and an optional version which defaults to v1
+If the entities are already registered with flyte for the same version then registration would fail.
+`
+)
+
 // RegisterCommand will return register command
 func RegisterCommand() *cobra.Command {
 	registerCmd := &cobra.Command{
 		Use:   "register",
-		Short: "Registers tasks/workflows/launchplans from list of generated serialized files.",
-		Long: "Takes input files as serialized versions of the tasks/workflows/launchplans and registers them with flyteadmin.\n" +
-			"Currently these input files are protobuf files generated as output from flytekit serialize.\n" +
-			"Project & Domain are mandatory fields to be passed for registration and an optional version which defaults to v1\n" +
-			"If the entities are already registered with flyte for the same version then registration would fail.\n",
+		Short: registerCmdShort,
+		Long:  registercmdLong,
 	}
 	registerResourcesFuncs := map[string]cmdcore.CommandEntry{
-		"files": {CmdFunc: registerFromFilesFunc, Aliases: []string{"file"}, PFlagProvider: filesConfig},
+		"files": {CmdFunc: registerFromFilesFunc, Aliases: []string{"file"}, PFlagProvider: filesConfig, Short: registerFilesShort,
+			Long: registerFilesLong},
 	}
 	cmdcore.AddCommands(registerCmd, registerResourcesFuncs)
 	return registerCmd