Set aliases using usage template

[navidshaikh]

Currently we've to manually document the aliases for the commands and flags, that should've been added by auto doc utility from cobra.
ref: #1041

[danielhelfand]

Is the goal here for just docs or to include in help command as well?

Something like below could very easily be added for help:

List services (alias: 'ls')

Examples:

  # List all services
  kn service list

  # List all services in JSON output format
  kn service list -o json

  # List service 'web'
  kn service list web


Options:
  -A, --all-namespaces                If present, list the requested object(s) across all namespaces. Namespace in current context is ignored even if specified with --namespace.
      --allow-missing-template-keys   If true, ignore any errors in templates when a field or map key is missing in the template. Only applies to golang and jsonpath output formats. (default true)
  -n, --namespace string              Specify the namespace to operate in.
      --no-headers                    When using the default output format, don't print headers (default: print headers).
  -o, --output string                 Output format. One of: json|yaml|name|go-template|go-template-file|template|templatefile|jsonpath|jsonpath-file.
      --template string               Template string or path to template file to use when -o=go-template, -o=go-template-file. The template format is golang templates
                                      [http://golang.org/pkg/text/template/#pkg-overview].

Usage:
  kn service list [options]

Aliases: 
  list, ls

Use "kn options" for a list of global command-line options (applies to all commands).

While updating generate-docs.go might require relying less on "github.com/spf13/cobra/doc" default doc generation approaches and implementing a custom approach, such as what tkn has done.

[navidshaikh]

I think having

Aliases: 
  list, ls

section for help text should do, I'd remove the inline hint of alias from the short description, in favor of former.

[navidshaikh]

looks like tkn is controlling the help text using usage template https://github.com/tektoncd/cli/blob/master/pkg/cmd/root.go#L43

[danielhelfand]

Yes, I put together something like below for kn:

	sectionAliases = `{{ if ne (len .Aliases) 0}}Aliases: 
  {{.NameAndAliases}}

{{end}}`

	// sectionTipsHelp is the help template section that displays the '--help' hint.
	sectionTipsHelp = `{{if .HasSubCommands}}Use "{{rootCmdName}} <command> --help" for more information about a given command.
{{end}}`

	// sectionTipsGlobalOptions is the help template section that displays the 'options' hint for displaying global flags.
	sectionTipsGlobalOptions = `Use "{{rootCmdName}} options" for a list of global command-line options (applies to all commands).`
)

// usageTemplate if the template for 'usage' used by most commands.
func usageTemplate() string {
	sections := []string{
		"\n\n",
		sectionExamples,
		sectionCommandGroups,
		sectionSubCommands,
		sectionPlugins,
		sectionFlags,
		sectionUsage,
		sectionAliases,
		sectionTipsHelp,
		sectionTipsGlobalOptions,
	}
	return strings.TrimRightFunc(strings.Join(sections, ""), unicode.IsSpace) + "\n"
}

Can put in a pr if it makes sense.

[navidshaikh]

nice! How about re-ordering of the subsections as:

"\n\n"
sectionUsage,
sectionAliases,
sectionExamples,
[..]

[danielhelfand]

Sure, sounds good. Let me rearrange and I'll submit something.