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,9 @@ func init() {
 
 func main() {
 	err := run(os.Args[1:])
-	if err != nil {
+	if err != nil && len(os.Args) > 1 {
 		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		fmt.Fprintf(os.Stderr, "Run '%s --help' for usage\n", extractCommandPathFromErrorMessage(err.Error(), os.Args[0]))
 		// This is the only point from where to exit when an error occurs
 		os.Exit(1)
 	}
@@ -106,8 +108,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 +180,22 @@ 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
 }
+
+// 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
+}

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 show 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 a revision
 * [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 a revision
 
 ### Synopsis
 
-Delete a revision.
+Delete a revision
 
 ```
-kn revision delete NAME [flags]
+kn revision delete 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
 

docs/cmd/kn_route.md

@@ -1,13 +1,13 @@
 ## kn route
 
-Route command group
+List and show service routes
 
 ### Synopsis
 
-Route command group
+List and show service routes
 
 ```
-kn route [flags]
+kn route
 ```
 
 ### Options
@@ -26,7 +26,7 @@ kn route [flags]
 
 ### SEE ALSO
 
-* [kn](kn.md)	 - Knative client
+* [kn](kn.md)	 - kn manages Knative Serving and Eventing resources
 * [kn route describe](kn_route_describe.md)	 - Show details of a route
-* [kn route list](kn_route_list.md)	 - List available routes.
+* [kn route list](kn_route_list.md)	 - List routes
 

docs/cmd/kn_route_describe.md

@@ -7,7 +7,7 @@ Show details of a route
 Show details of a route
 
 ```
-kn route describe NAME [flags]
+kn route describe NAME
 ```
 
 ### Options
@@ -31,5 +31,5 @@ kn route describe NAME [flags]
 
 ### SEE ALSO
 
-* [kn route](kn_route.md)	 - Route command group
+* [kn route](kn_route.md)	 - List and show service routes
 

docs/cmd/kn_route_list.md

@@ -1,13 +1,13 @@
 ## kn route list
 
-List available routes.
+List routes
 
 ### Synopsis
 
-List available routes.
+List routes
 
 ```
-kn route list NAME [flags]
+kn route list NAME
 ```
 
 ### Examples
@@ -46,5 +46,5 @@ kn route list NAME [flags]
 
 ### SEE ALSO
 
-* [kn route](kn_route.md)	 - Route command group
+* [kn route](kn_route.md)	 - List and show service routes
 

docs/cmd/kn_service.md

@@ -1,13 +1,13 @@
 ## kn service
 
-Service command group
+Manage Knative services
 
 ### Synopsis
 
-Service command group
+Manage Knative services
 
 ```
-kn service [flags]
+kn service
 ```
 
 ### Options
@@ -26,11 +26,11 @@ kn service [flags]
 
 ### SEE ALSO
 
-* [kn](kn.md)	 - Knative client
-* [kn service create](kn_service_create.md)	 - Create a service.
-* [kn service delete](kn_service_delete.md)	 - Delete a service.
+* [kn](kn.md)	 - kn manages Knative Serving and Eventing resources
+* [kn service create](kn_service_create.md)	 - Create a service
+* [kn service delete](kn_service_delete.md)	 - Delete a service
 * [kn service describe](kn_service_describe.md)	 - Show details of a service
-* [kn service export](kn_service_export.md)	 - Export a service.
-* [kn service list](kn_service_list.md)	 - List available services.
-* [kn service update](kn_service_update.md)	 - Update a service.
+* [kn service export](kn_service_export.md)	 - Export a service and its revisions
+* [kn service list](kn_service_list.md)	 - List available services
+* [kn service update](kn_service_update.md)	 - Update a service