Add grouping for help message + streamlined help messages

cmd/kn/main.go

@@ -18,6 +18,7 @@ import (
 	"fmt"
 	"math/rand"
 	"os"
+	"regexp"
 	"strings"
 	"time"
 
@@ -35,8 +36,8 @@ func init() {
 
 func main() {
 	err := run(os.Args[1:])
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+	if err != nil && len(os.Args) > 1 {
+		printError(err)
 		// This is the only point from where to exit when an error occurs
 		os.Exit(1)
 	}
@@ -106,8 +107,14 @@ func stripFlags(args []string) ([]string, error) {
 				*commandsFound = append(*commandsFound, arg)
 			}
 		},
+		SilenceErrors: true,
+		SilenceUsage:  true,
 	}
 
+	// No help and usage functions to prin
+	extractCommand.SetHelpFunc(func(*cobra.Command, []string) {})
+	extractCommand.SetUsageFunc(func(*cobra.Command) error { return nil })
+
 	// Filter out --help and -h options to avoid special treatment which we don't
 	// need here
 	extractCommand.SetArgs(filterHelpOptions(args))
@@ -172,10 +179,34 @@ func validateRootCommand(cmd *cobra.Command) error {
 	if err == nil && foundCmd.HasSubCommands() && len(innerArgs) > 0 {
 		argsWithoutFlags, err := stripFlags(innerArgs)
 		if len(argsWithoutFlags) > 0 || err != nil {
-			return errors.Errorf("unknown sub-command '%s' for '%s'. Available sub-commands: %s", innerArgs[0], foundCmd.Name(), strings.Join(root.ExtractSubCommandNames(foundCmd.Commands()), ", "))
+			return errors.Errorf("unknown sub-command '%s' for '%s'. Available sub-commands: %s", innerArgs[0], foundCmd.CommandPath(), strings.Join(root.ExtractSubCommandNames(foundCmd.Commands()), ", "))
 		}
 		// If no args where given (only flags), then fall through to execute the command itself, which leads to
 		// a more appropriate error message
 	}
 	return nil
 }
+
+// printError prints out any given error
+func printError(err error) {
+	fmt.Fprintf(os.Stderr, "Error: %s\n", cleanupErrorMessage(err.Error()))
+	fmt.Fprintf(os.Stderr, "Run '%s --help' for usage\n", extractCommandPathFromErrorMessage(err.Error(), os.Args[0]))
+}
+
+// extractCommandPathFromErrorMessage tries to extract the command name from an error message
+// by checking a pattern like 'kn service' in the error message. If not found, return the
+// base command name.
+func extractCommandPathFromErrorMessage(errorMsg string, arg0 string) string {
+	extractPattern := regexp.MustCompile(fmt.Sprintf("'(%s\\s.+?)'", arg0))
+	command := extractPattern.FindSubmatch([]byte(errorMsg))
+	if command != nil {
+		return string(command[1])
+	}
+	return arg0
+}
+
+// cleanupErrorMessage remove any redundance content of an error message
+func cleanupErrorMessage(msg string) string {
+	regexp := regexp.MustCompile("(?i)^error:\\s*")
+	return string(regexp.ReplaceAll([]byte(msg), []byte("")))
+}

cmd/kn/main_test.go

@@ -15,14 +15,16 @@
 package main
 
 import (
+	"errors"
 	"fmt"
 	"os"
+	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 	"gotest.tools/assert"
 
-	"knative.dev/client/pkg/kn/commands"
+	"knative.dev/client/lib/test"
 	"knative.dev/client/pkg/kn/root"
 	"knative.dev/client/pkg/util"
 )
@@ -226,6 +228,31 @@ func TestStripFlags(t *testing.T) {
 	}
 }
 
+func TestRunWithError(t *testing.T) {
+	data := []struct {
+		given    string
+		expected string
+	}{
+		{
+			"unknown sub-command blub",
+			"Error: unknown sub-command blub",
+		},
+		{
+			"error: unknown type blub",
+			"Error: unknown type blub",
+		},
+	}
+	for _, d := range data {
+		capture := test.CaptureOutput(t)
+		printError(errors.New(d.given))
+		stdOut, errOut := capture.Close()
+
+		assert.Equal(t, stdOut, "")
+		assert.Assert(t, strings.Contains(errOut, d.expected))
+		assert.Assert(t, util.ContainsAll(errOut, "Run", "--help", "usage"))
+	}
+}
+
 // Smoke test
 func TestRun(t *testing.T) {
 	oldArgs := os.Args
@@ -234,9 +261,9 @@ func TestRun(t *testing.T) {
 		os.Args = oldArgs
 	})()
 
-	capture := commands.CaptureStdout(t)
+	capture := test.CaptureOutput(t)
 	err := run(os.Args[1:])
-	out := capture.Close()
+	out, _ := capture.Close()
 
 	assert.NilError(t, err)
 	assert.Assert(t, util.ContainsAllIgnoreCase(out, "version", "build", "git"))

conventions/cli.md

@@ -51,6 +51,7 @@ be used:
 - `create` creates a resource.
 - `update` updates a resource.
 - `delete` deletes a resource.
+- `apply` for an idempotent "create-or-update", much like `kubetl apply`
 
 For a given resource, create and update should use the same arguments as much as
 possible and where it makes sense.
@@ -84,6 +85,7 @@ Flags are used for specifying the input for `kn` commands and can have different
 characteristics:
 
 - They can be _mandatory_ or _optional_
+- Mandatory flags are mentioned in the `Use` attribute of a command like in `service NAME --image IMAGE` for `ServiceCommand`
 - Optional flags can have _default values_
 - Flag values can be _scalars_, _binary_, _lists_ or _maps_ (see below for
   details)

docs/cmd/kn.md

@@ -1,13 +1,12 @@
 ## kn
 
-Knative client
+kn manages Knative Serving and Eventing resources
 
 ### Synopsis
 
-Manage your Knative building blocks:
+kn is the command line interface for managing Knative Serving and Eventing resources
 
-* Serving: Manage your services and release new software to them.
-* Eventing: Manage event subscriptions and channels. Connect up event sources.
+ Find more information about Knative at: https://knative.dev
 
 ### Options
 
@@ -21,11 +20,12 @@ Manage your Knative building blocks:
 ### SEE ALSO
 
 * [kn completion](kn_completion.md)	 - Output shell completion code
-* [kn plugin](kn_plugin.md)	 - Plugin command group
-* [kn revision](kn_revision.md)	 - Revision command group
-* [kn route](kn_route.md)	 - Route command group
-* [kn service](kn_service.md)	 - Service command group
-* [kn source](kn_source.md)	 - Event source command group
-* [kn trigger](kn_trigger.md)	 - Trigger command group
-* [kn version](kn_version.md)	 - Prints the client version
+* [kn options](kn_options.md)	 - Print the list of flags inherited by all commands
+* [kn plugin](kn_plugin.md)	 - Manage kn plugins
+* [kn revision](kn_revision.md)	 - Manage service revisions
+* [kn route](kn_route.md)	 - List and describe service routes
+* [kn service](kn_service.md)	 - Manage Knative services
+* [kn source](kn_source.md)	 - Manage event sources
+* [kn trigger](kn_trigger.md)	 - Manage event triggers
+* [kn version](kn_version.md)	 - Show the version of this client
 

docs/cmd/kn_completion.md

@@ -13,7 +13,7 @@ Supported Shells:
  - zsh
 
 ```
-kn completion [SHELL] [flags]
+kn completion SHELL
 ```
 
 ### Examples
@@ -44,5 +44,5 @@ kn completion [SHELL] [flags]
 
 ### SEE ALSO
 
-* [kn](kn.md)	 - Knative client
+* [kn](kn.md)	 - kn manages Knative Serving and Eventing resources
 

docs/cmd/kn_options.md

@@ -0,0 +1,37 @@
+## kn options
+
+Print the list of flags inherited by all commands
+
+### Synopsis
+
+Print the list of flags inherited by all commands
+
+```
+kn options [flags]
+```
+
+### Examples
+
+```
+# Print flags inherited by all commands
+kn options
+```
+
+### Options
+
+```
+  -h, --help   help for options
+```
+
+### Options inherited from parent commands
+
+```
+      --config string       kn configuration file (default: ~/.config/kn/config.yaml)
+      --kubeconfig string   kubectl configuration file (default: ~/.kube/config)
+      --log-http            log http traffic
+```
+
+### SEE ALSO
+
+* [kn](kn.md)	 - kn manages Knative Serving and Eventing resources
+

docs/cmd/kn_plugin.md

@@ -1,16 +1,16 @@
 ## kn plugin
 
-Plugin command group
+Manage kn plugins
 
 ### Synopsis
 
-Provides utilities for interacting and managing with kn plugins.
+Manage kn plugins
 
 Plugins provide extended functionality that is not part of the core kn command-line distribution.
-Please refer to the documentation and examples for more information about how write your own plugins.
+Please refer to the documentation and examples for more information about how to write your own plugins.
 
 ```
-kn plugin [flags]
+kn plugin
 ```
 
 ### Options
@@ -29,6 +29,6 @@ kn plugin [flags]
 
 ### SEE ALSO
 
-* [kn](kn.md)	 - Knative client
+* [kn](kn.md)	 - kn manages Knative Serving and Eventing resources
 * [kn plugin list](kn_plugin_list.md)	 - List plugins
 

docs/cmd/kn_plugin_list.md

@@ -10,10 +10,10 @@ Available plugins are those that are:
 - executable
 - begin with "kn-"
 - Kn's plugin directory
-- Anywhere in the execution $PATH (if plugins.path-lookup config variable is enabled)
+- Anywhere in the execution $PATH (if plugins.path-lookup configuration variable is enabled)
 
 ```
-kn plugin list [flags]
+kn plugin list
 ```
 
 ### Options
@@ -33,5 +33,5 @@ kn plugin list [flags]
 
 ### SEE ALSO
 
-* [kn plugin](kn_plugin.md)	 - Plugin command group
+* [kn plugin](kn_plugin.md)	 - Manage kn plugins
 

docs/cmd/kn_revision.md

@@ -1,13 +1,13 @@
 ## kn revision
 
-Revision command group
+Manage service revisions
 
 ### Synopsis
 
-Revision command group
+Manage service revisions
 
 ```
-kn revision [flags]
+kn revision
 ```
 
 ### Options
@@ -26,8 +26,8 @@ kn revision [flags]
 
 ### SEE ALSO
 
-* [kn](kn.md)	 - Knative client
-* [kn revision delete](kn_revision_delete.md)	 - Delete a revision.
+* [kn](kn.md)	 - kn manages Knative Serving and Eventing resources
+* [kn revision delete](kn_revision_delete.md)	 - Delete revisions
 * [kn revision describe](kn_revision_describe.md)	 - Show details of a revision
-* [kn revision list](kn_revision_list.md)	 - List available revisions.
+* [kn revision list](kn_revision_list.md)	 - List revisions
 

docs/cmd/kn_revision_delete.md

@@ -1,13 +1,13 @@
 ## kn revision delete
 
-Delete a revision.
+Delete revisions
 
 ### Synopsis
 
-Delete a revision.
+Delete revisions
 
 ```
-kn revision delete NAME [flags]
+kn revision delete NAME [NAME ...]
 ```
 
 ### Examples
@@ -39,5 +39,5 @@ kn revision delete NAME [flags]
 
 ### SEE ALSO
 
-* [kn revision](kn_revision.md)	 - Revision command group
+* [kn revision](kn_revision.md)	 - Manage service revisions
 

docs/cmd/kn_revision_describe.md

@@ -7,7 +7,7 @@ Show details of a revision
 Show details of a revision
 
 ```
-kn revision describe NAME [flags]
+kn revision describe NAME
 ```
 
 ### Options
@@ -31,5 +31,5 @@ kn revision describe NAME [flags]
 
 ### SEE ALSO
 
-* [kn revision](kn_revision.md)	 - Revision command group
+* [kn revision](kn_revision.md)	 - Manage service revisions
 

docs/cmd/kn_revision_list.md

@@ -1,13 +1,13 @@
 ## kn revision list
 
-List available revisions.
+List revisions
 
 ### Synopsis
 
 List revisions for a given service.
 
 ```
-kn revision list [name] [flags]
+kn revision list
 ```
 
 ### Examples
@@ -50,5 +50,5 @@ kn revision list [name] [flags]
 
 ### SEE ALSO
 
-* [kn revision](kn_revision.md)	 - Revision command group
+* [kn revision](kn_revision.md)	 - Manage service revisions