src: add Long command descriptions for each of the CLI commands (#133)

Uses the Cobra "Long" configuration for each command to provide more
descriptive text.

Example:

```console
faas help create                                                                                                      1.3m  Mon 21 Sep 2020 09:55:40 PM EDT
Create a new Function, including initialization of local files and deployment

Creates a new Function project at 'path'. If 'path' does not exist, it is
created. The function name is the name of the leaf directory at path. After
creating the project, a container image is created and is deployed. This
command wraps 'init', 'build' and 'deploy' all up into one command.

The runtime, trigger, image name, image repository, and namespace may all be
specified as flags on the command line, and will subsequently be the default
values when an image is built or a Function is deployed. If the image name and
image repository are both unspecified, the user will be prompted for a
repository name, and the image name can be inferred from that plus the function
name. The function name, namespace, image name and repository name are all
persisted in the project configuration file .faas.yaml.

Usage:
  faas create <path> [options] [flags]

Flags:
  -c, --confirm             Prompt to confirm all configuration options - $FAAS_CONFIRM
  -h, --help                help for create
  -i, --image string        Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --repository) - $FAAS_IMAGE
  -n, --namespace string    Override namespace into which the Function is deployed (on supported platforms).  Default is to use currently active underlying platform setting - $FAAS_NAMESPACE
  -r, --repository string   Repository for built images, ex 'docker.io/myuser' or just 'myuser'.  Optional if --image provided. - $FAAS_REPOSITORY
  -l, --runtime string      Function runtime language/framework. - $FAAS_RUNTIME (default "go")
      --templates string    Extensible templates path. - $FAAS_TEMPLATES (default "/home/lanceball/.config/faas/templates")
  -t, --trigger string      Function trigger (ex: 'http','events') - $FAAS_TRIGGER (default "http")

Global Flags:
      --config string   config file path (default "~/.faas/config")
  -v, --verbose         print verbose logs
```

cmd/build.go

@@ -20,8 +20,20 @@ func init() {
 }
 
 var buildCmd = &cobra.Command{
-	Use:        "build",
-	Short:      "Build an existing Function project as an OCI image",
+	Use:   "build",
+	Short: "Build an existing Function project as an OCI image",
+	Long: `Build an existing Function project as an OCI image
+
+Builds the Function project in the current directory or in the directory
+specified by the --path flag. The .faas.yaml file is read to determine the
+image name and repository. If both of these values are unset in the
+configuration file the --repository or -r flag should be provided and an image
+name will be derived from the project name.
+
+Any value provided for --image or --repository will be persisted in the
+.faas.yaml configuration file. On subsequent invocations of the "build" command
+these values will be read from the configuration file.
+`,
 	SuggestFor: []string{"biuld", "buidl", "built"},
 	PreRunE:    bindEnv("image", "path", "repository", "confirm"),
 	RunE:       runBuild,

cmd/create.go

@@ -21,9 +21,9 @@ func init() {
 	createCmd.Flags().StringP("image", "i", "", "Optional full image name, in form [registry]/[namespace]/[name]:[tag] for example quay.io/myrepo/project.name:latest (overrides --repository) - $FAAS_IMAGE")
 	createCmd.Flags().StringP("namespace", "n", "", "Override namespace into which the Function is deployed (on supported platforms).  Default is to use currently active underlying platform setting - $FAAS_NAMESPACE")
 	createCmd.Flags().StringP("repository", "r", "", "Repository for built images, ex 'docker.io/myuser' or just 'myuser'.  Optional if --image provided. - $FAAS_REPOSITORY")
-	createCmd.Flags().StringP("runtime", "l", faas.DefaultRuntime, "Function runtime language/framework. - $FAAS_RUNTIME")
+	createCmd.Flags().StringP("runtime", "l", faas.DefaultRuntime, "Function runtime language/framework. Default runtime is 'go'. Available runtimes: 'node', 'quarkus' and 'go'. - $FAAS_RUNTIME")
 	createCmd.Flags().StringP("templates", "", filepath.Join(configPath(), "templates"), "Extensible templates path. - $FAAS_TEMPLATES")
-	createCmd.Flags().StringP("trigger", "t", faas.DefaultTrigger, "Function trigger (ex: 'http','events') - $FAAS_TRIGGER")
+	createCmd.Flags().StringP("trigger", "t", faas.DefaultTrigger, "Function trigger. Default trigger is 'http'. Available triggers: 'http' and 'events' - $FAAS_TRIGGER")
 
 	var err error
 	err = createCmd.RegisterFlagCompletionFunc("image", CompleteRegistryList)
@@ -37,8 +37,23 @@ func init() {
 }
 
 var createCmd = &cobra.Command{
-	Use:        "create <path>",
-	Short:      "Create a new Function, including initialization of local files and deployment.",
+	Use:   "create <path>",
+	Short: "Create a new Function, including initialization of local files and deployment",
+	Long: `Create a new Function, including initialization of local files and deployment
+
+Creates a new Function project at <path>. If <path> does not exist, it is
+created. The Function name is the name of the leaf directory at <path>. After
+creating the project, a container image is created and is deployed. This
+command wraps "init", "build" and "deploy" all up into one command.
+
+The runtime, trigger, image name, image repository, and namespace may all be
+specified as flags on the command line, and will subsequently be the default
+values when an image is built or a Function is deployed. If the image name and
+image repository are both unspecified, the user will be prompted for a
+repository name, and the image name can be inferred from that plus the function
+name. The function name, namespace, image name and repository name are all
+persisted in the project configuration file .faas.yaml.
+`,
 	SuggestFor: []string{"cerate", "new"},
 	PreRunE:    bindEnv("image", "namespace", "repository", "runtime", "templates", "trigger", "confirm"),
 	RunE:       runCreate,

cmd/delete.go

@@ -17,9 +17,20 @@ func init() {
 }
 
 var deleteCmd = &cobra.Command{
-	Use:               "delete <name>",
-	Short:             "Delete a Function deployment",
-	Long:              `Removes the deployed Function by name, by explicit path, or by default for the current directory.  No local files are deleted.`,
+	Use:   "delete <name>",
+	Short: "Delete a Function deployment",
+	Long: `Delete a Function deployment
+
+Removes a deployed function from the cluster. The user may specify a function
+by name, path using the --path or -p flag, or if neither of those are provided,
+the current directory will be searched for a .faas.yaml configuration file to
+determine the function to be removed.
+
+The namespace defaults to the value in .faas.yaml or the namespace currently
+active in the user's Kubernetes configuration. The namespace may be specified
+on the command line using the --namespace or -n flag, and if so this will
+overwrite the value in .faas.yaml.
+`,
 	SuggestFor:        []string{"remove", "rm", "del"},
 	ValidArgsFunction: CompleteFunctionList,
 	PreRunE:           bindEnv("path", "confirm", "namespace"),

cmd/deploy.go

@@ -20,8 +20,20 @@ func init() {
 }
 
 var deployCmd = &cobra.Command{
-	Use:        "deploy",
-	Short:      "Deploy an existing Function project to a cluster",
+	Use:   "deploy",
+	Short: "Deploy an existing Function project to a cluster",
+	Long: `Deploy an existing Function project to a cluster
+
+Deploys the Function project in the current directory. A path to the project
+directory may be provided using the --path or -p flag. The image to be deployed
+must have already been created using the "build" command.
+
+The namespace into which the project is deployed defaults to the value in the
+.faas.yaml configuration file. If NAMESPACE is not set in the configuration,
+the namespace currently active in the Kubernetes configuration file will be
+used. The namespace may be specified on the command line using the --namespace
+or -n flag, and if so this will overwrite the value in the .faas.yaml file.
+`,
 	SuggestFor: []string{"delpoy", "deplyo"},
 	PreRunE:    bindEnv("namespace", "path", "confirm"),
 	RunE:       runDeploy,

cmd/describe.go

@@ -28,9 +28,18 @@ func init() {
 }
 
 var describeCmd = &cobra.Command{
-	Use:               "describe <name>",
-	Short:             "Describe Function",
-	Long:              `Describes the Function initialized in the current directory, or by passed name argument.`,
+	Use:   "describe <name>",
+	Short: "Describes the Function",
+	Long: `Describes the Function
+
+Prints the name, route and any event subscriptions for a deployed Function in
+the current directory. A path to a Function project directory may be supplied
+using the --path or -p flag.
+
+The namespace defaults to the value in .faas.yaml or the namespace currently
+active in the user's Kubernetes configuration. The namespace may be specified
+using the --namespace or -n flag, and if so this will overwrite the value in .faas.yaml.
+`,
 	SuggestFor:        []string{"desc", "get"},
 	ValidArgsFunction: CompleteFunctionList,
 	PreRunE:           bindEnv("namespace", "format", "path"),

cmd/init.go

@@ -14,18 +14,31 @@ import (
 func init() {
 	root.AddCommand(initCmd)
 	initCmd.Flags().BoolP("confirm", "c", false, "Prompt to confirm all configuration options - $FAAS_CONFIRM")
-	initCmd.Flags().StringP("runtime", "l", faas.DefaultRuntime, "Function runtime language/framework. - $FAAS_RUNTIME")
+	initCmd.Flags().StringP("runtime", "l", faas.DefaultRuntime, "Function runtime language/framework. Default runtime is 'go'. Available runtimes: 'node', 'quarkus' and 'go'. - $FAAS_RUNTIME")
 	initCmd.Flags().StringP("templates", "", filepath.Join(configPath(), "templates"), "Extensible templates path. - $FAAS_TEMPLATES")
-	initCmd.Flags().StringP("trigger", "t", faas.DefaultTrigger, "Function trigger (ex: 'http','events') - $FAAS_TRIGGER")
+	initCmd.Flags().StringP("trigger", "t", faas.DefaultTrigger, "Function trigger. Default trigger is 'http'. Available triggers: 'http' and 'events' - $FAAS_TRIGGER")
 
 	if err := initCmd.RegisterFlagCompletionFunc("runtime", CompleteRuntimeList); err != nil {
 		fmt.Println("Error while calling RegisterFlagCompletionFunc: ", err)
 	}
 }
 
 var initCmd = &cobra.Command{
-	Use:        "init <path>",
-	Short:      "Initialize a new Function project",
+	Use:   "init <path>",
+	Short: "Initialize a new Function project",
+	Long: `Initializes a new Function project
+
+Creates a new Function project at <path>. If <path> does not exist, it is
+created. The Function name is the name of the leaf directory at <path>.
+
+A project for a Go Function will be created by default. Specify an alternate
+runtime with the --language or -l flag. Available alternates are "node" and
+"quarkus".
+
+Use the --trigger or -t flag to specify the function invocation context.
+By default, the trigger is "http". To create a Function for CloudEvents, use
+"events".
+`,
 	SuggestFor: []string{"inti", "new"},
 	PreRunE:    bindEnv("runtime", "templates", "trigger", "confirm"),
 	RunE:       runInit,

cmd/list.go

@@ -27,9 +27,15 @@ func init() {
 }
 
 var listCmd = &cobra.Command{
-	Use:        "list",
-	Short:      "Lists deployed Functions",
-	Long:       `Lists deployed Functions`,
+	Use:   "list",
+	Short: "Lists deployed Functions",
+	Long: `Lists deployed Functions
+
+Lists all deployed functions. The namespace defaults to the value in .faas.yaml
+or the namespace currently active in the user's Kubernetes configuration. The
+namespace may be specified on the command line using the --namespace or -n flag.
+If specified this will overwrite the value in .faas.yaml.
+`,
 	SuggestFor: []string{"ls", "lsit"},
 	PreRunE:    bindEnv("namespace", "format"),
 	RunE:       runList,

cmd/run.go

@@ -15,9 +15,13 @@ func init() {
 
 var runCmd = &cobra.Command{
 	Use:   "run",
-	Short: "Run Function locally",
-	Long:  "Runs the function locally within an isolated environment.  Modifications to the Function trigger a reload.  This holds open the current window with the logs from the running Function, and the run is canceled on interrupt.",
-	RunE:  runRun,
+	Short: "Runs the Function locally",
+	Long: `Runs the Function locally
+
+Runs the project in the deployable image. The project must already have been
+built as an OCI container image using the 'build' command.
+`,
+	RunE: runRun,
 }
 
 func runRun(cmd *cobra.Command, args []string) (err error) {

cmd/update.go

@@ -22,9 +22,27 @@ func init() {
 }
 
 var updateCmd = &cobra.Command{
-	Use:        "update",
-	Short:      "Update or create a deployed Function",
-	Long:       `Update deployed Function to match the current local state.`,
+	Use:   "update",
+	Short: "Update a deployed Function",
+	Long: `Update a deployed Function
+
+Updates the deployed Function project in the current directory or in the
+directory specified by the --path flag. Reads the .faas.yaml configuration file
+to determine the image name.
+
+The deployed Function is updated with a new container image that is pushed to a
+container image repository, and the Knative Service is updated.
+
+The namespace defaults to the value in .faas.yaml or the namespace currently
+active in the user Kubernetes configuration. The namespace may be specified on
+the command line, and if so this will overwrite the value in .faas.yaml.
+
+An image repository may be specified on the command line using the --repository
+or -r flag.
+
+Note that the behavior of update is different than that of deploy and run.  When
+update is run, a new container image is always built.
+`,
 	SuggestFor: []string{"push", "deploy"},
 	PreRunE:    bindEnv("namespace", "path", "repository", "confirm"),
 	RunE:       runUpdate,

go.mod

@@ -14,7 +14,6 @@ require (
 	github.com/ory/viper v1.7.4
 	github.com/spf13/cobra v1.0.0
 	github.com/stretchr/testify v1.5.1 // indirect
-	golang.org/x/net v0.0.0-20200520004742-59133d7f0dd7
 	golang.org/x/sys v0.0.0-20200728102440-3e129f6d46b1 // indirect
 	gopkg.in/yaml.v2 v2.3.0
 	k8s.io/api v0.17.4