update vendor spf13/cobra to enforce required flags

Godeps/Godeps.json

@@ -2470,11 +2470,11 @@
 		},
 		{
 			"ImportPath": "github.com/spf13/cobra",
-			"Rev": "f62e98d28ab7ad31d707ba837a966378465c7b57"
+			"Rev": "19e54c4a2b8a78c9d54b2bed61b1a6c5e1bfcf6f"
 		},
 		{
 			"ImportPath": "github.com/spf13/cobra/doc",
-			"Rev": "f62e98d28ab7ad31d707ba837a966378465c7b57"
+			"Rev": "19e54c4a2b8a78c9d54b2bed61b1a6c5e1bfcf6f"
 		},
 		{
 			"ImportPath": "github.com/spf13/jwalterweatherman",

staging/src/k8s.io/apiextensions-apiserver/Godeps/Godeps.json

@@ -328,7 +328,7 @@
 		},
 		{
 			"ImportPath": "github.com/spf13/cobra",
-			"Rev": "f62e98d28ab7ad31d707ba837a966378465c7b57"
+			"Rev": "19e54c4a2b8a78c9d54b2bed61b1a6c5e1bfcf6f"
 		},
 		{
 			"ImportPath": "github.com/spf13/pflag",

staging/src/k8s.io/kube-aggregator/Godeps/Godeps.json

@@ -308,7 +308,7 @@
 		},
 		{
 			"ImportPath": "github.com/spf13/cobra",
-			"Rev": "f62e98d28ab7ad31d707ba837a966378465c7b57"
+			"Rev": "19e54c4a2b8a78c9d54b2bed61b1a6c5e1bfcf6f"
 		},
 		{
 			"ImportPath": "github.com/spf13/pflag",

staging/src/k8s.io/sample-apiserver/Godeps/Godeps.json

@@ -296,7 +296,7 @@
 		},
 		{
 			"ImportPath": "github.com/spf13/cobra",
-			"Rev": "f62e98d28ab7ad31d707ba837a966378465c7b57"
+			"Rev": "19e54c4a2b8a78c9d54b2bed61b1a6c5e1bfcf6f"
 		},
 		{
 			"ImportPath": "github.com/spf13/pflag",

vendor/github.com/spf13/cobra/.travis.yml

 language: go
-go:
-  - 1.4.3
-  - 1.5.4
-  - 1.6.3
-  - tip
 
 matrix:
+  include:
+    - go: 1.7.6
+    - go: 1.8.3
+    - go: tip
   allow_failures:
     - go: tip
 
@@ -16,3 +15,7 @@ before_install:
 script:
   - PATH=$PATH:$PWD/bin go test -v ./...
   - go build
+  - diff -u <(echo -n) <(gofmt -d -s .)
+  - if [ -z $NOVET ]; then
+      diff -u <(echo -n) <(go tool vet . 2>&1 | grep -vE 'ExampleCommand|bash_completions.*Fprint');
+    fi

vendor/github.com/spf13/cobra/BUILD

@@ -3,9 +3,11 @@ load("@io_bazel_rules_go//go:def.bzl", "go_library")
 go_library(
     name = "go_default_library",
     srcs = [
+        "args.go",
         "bash_completions.go",
         "cobra.go",
         "command.go",
+        "zsh_completions.go",
     ] + select({
         "@io_bazel_rules_go//go/platform:android": [
             "command_notwin.go",

vendor/github.com/spf13/cobra/args.go

+package cobra
+
+import (
+	"fmt"
+)
+
+type PositionalArgs func(cmd *Command, args []string) error
+
+// Legacy arg validation has the following behaviour:
+// - root commands with no subcommands can take arbitrary arguments
+// - root commands with subcommands will do subcommand validity checking
+// - subcommands will always accept arbitrary arguments
+func legacyArgs(cmd *Command, args []string) error {
+	// no subcommand, always take args
+	if !cmd.HasSubCommands() {
+		return nil
+	}
+
+	// root command with subcommands, do subcommand checking.
+	if !cmd.HasParent() && len(args) > 0 {
+		return fmt.Errorf("unknown command %q for %q%s", args[0], cmd.CommandPath(), cmd.findSuggestions(args[0]))
+	}
+	return nil
+}
+
+// NoArgs returns an error if any args are included.
+func NoArgs(cmd *Command, args []string) error {
+	if len(args) > 0 {
+		return fmt.Errorf("unknown command %q for %q", args[0], cmd.CommandPath())
+	}
+	return nil
+}
+
+// OnlyValidArgs returns an error if any args are not in the list of ValidArgs.
+func OnlyValidArgs(cmd *Command, args []string) error {
+	if len(cmd.ValidArgs) > 0 {
+		for _, v := range args {
+			if !stringInSlice(v, cmd.ValidArgs) {
+				return fmt.Errorf("invalid argument %q for %q%s", v, cmd.CommandPath(), cmd.findSuggestions(args[0]))
+			}
+		}
+	}
+	return nil
+}
+
+// ArbitraryArgs never returns an error.
+func ArbitraryArgs(cmd *Command, args []string) error {
+	return nil
+}
+
+// MinimumNArgs returns an error if there is not at least N args.
+func MinimumNArgs(n int) PositionalArgs {
+	return func(cmd *Command, args []string) error {
+		if len(args) < n {
+			return fmt.Errorf("requires at least %d arg(s), only received %d", n, len(args))
+		}
+		return nil
+	}
+}
+
+// MaximumNArgs returns an error if there are more than N args.
+func MaximumNArgs(n int) PositionalArgs {
+	return func(cmd *Command, args []string) error {
+		if len(args) > n {
+			return fmt.Errorf("accepts at most %d arg(s), received %d", n, len(args))
+		}
+		return nil
+	}
+}
+
+// ExactArgs returns an error if there are not exactly n args.
+func ExactArgs(n int) PositionalArgs {
+	return func(cmd *Command, args []string) error {
+		if len(args) != n {
+			return fmt.Errorf("accepts %d arg(s), received %d", n, len(args))
+		}
+		return nil
+	}
+}
+
+// RangeArgs returns an error if the number of args is not within the expected range.
+func RangeArgs(min int, max int) PositionalArgs {
+	return func(cmd *Command, args []string) error {
+		if len(args) < min || len(args) > max {
+			return fmt.Errorf("accepts between %d and %d arg(s), received %d", min, max, len(args))
+		}
+		return nil
+	}
+}

vendor/github.com/spf13/cobra/bash_completions.md

@@ -18,7 +18,7 @@ func main() {
 }
 ```
 
-That will get you completions of subcommands and flags. If you make additional annotations to your code, you can get even more intelligent and flexible behavior.
+`out.sh` will get you completions of subcommands and flags. Copy it to `/etc/bash_completion.d/` as described [here](https://debian-administration.org/article/316/An_introduction_to_bash_completion_part_1) and reset your terminal to use autocompletion. If you make additional annotations to your code, you can get even more intelligent and flexible behavior.
 
 ## Creating your own custom functions
 
@@ -106,7 +106,7 @@ node                 pod                    replicationcontroller  service
 
 If your nouns have a number of aliases, you can define them alongside `ValidArgs` using `ArgAliases`:
 
-```go`
+```go
 argAliases []string = { "pods", "nodes", "services", "svc", "replicationcontrollers", "rc" }
 
 cmd := &cobra.Command{

vendor/github.com/spf13/cobra/cobra.go

@@ -29,6 +29,7 @@ import (
 var templateFuncs = template.FuncMap{
 	"trim":                    strings.TrimSpace,
 	"trimRightSpace":          trimRightSpace,
+	"trimTrailingWhitespaces": trimRightSpace,
 	"appendIfNotPresent":      appendIfNotPresent,
 	"rpad":                    rpad,
 	"gt":                      Gt,
@@ -37,38 +38,48 @@ var templateFuncs = template.FuncMap{
 
 var initializers []func()
 
-// automatic prefix matching can be a dangerous thing to automatically enable in CLI tools.
-// Set this to true to enable it
+// EnablePrefixMatching allows to set automatic prefix matching. Automatic prefix matching can be a dangerous thing
+// to automatically enable in CLI tools.
+// Set this to true to enable it.
 var EnablePrefixMatching = false
 
-//EnableCommandSorting controls sorting of the slice of commands, which is turned on by default.
-//To disable sorting, set it to false.
+// EnableCommandSorting controls sorting of the slice of commands, which is turned on by default.
+// To disable sorting, set it to false.
 var EnableCommandSorting = true
 
-//AddTemplateFunc adds a template function that's available to Usage and Help
-//template generation.
+// MousetrapHelpText enables an information splash screen on Windows
+// if the CLI is started from explorer.exe.
+// To disable the mousetrap, just set this variable to blank string ("").
+// Works only on Microsoft Windows.
+var MousetrapHelpText string = `This is a command line tool.
+
+You need to open cmd.exe and run it from there.
+`
+
+// AddTemplateFunc adds a template function that's available to Usage and Help
+// template generation.
 func AddTemplateFunc(name string, tmplFunc interface{}) {
 	templateFuncs[name] = tmplFunc
 }
 
-//AddTemplateFuncs adds multiple template functions availalble to Usage and
-//Help template generation.
+// AddTemplateFuncs adds multiple template functions that are available to Usage and
+// Help template generation.
 func AddTemplateFuncs(tmplFuncs template.FuncMap) {
 	for k, v := range tmplFuncs {
 		templateFuncs[k] = v
 	}
 }
 
-//OnInitialize takes a series of func() arguments and appends them to a slice of func().
+// OnInitialize takes a series of func() arguments and appends them to a slice of func().
 func OnInitialize(y ...func()) {
-	for _, x := range y {
-		initializers = append(initializers, x)
-	}
+	initializers = append(initializers, y...)
 }
 
-//Gt takes two types and checks whether the first type is greater than the second. In case of types Arrays, Chans,
-//Maps and Slices, Gt will compare their lengths. Ints are compared directly while strings are first parsed as
-//ints and then compared.
+// FIXME Gt is unused by cobra and should be removed in a version 2. It exists only for compatibility with users of cobra.
+
+// Gt takes two types and checks whether the first type is greater than the second. In case of types Arrays, Chans,
+// Maps and Slices, Gt will compare their lengths. Ints are compared directly while strings are first parsed as
+// ints and then compared.
 func Gt(a interface{}, b interface{}) bool {
 	var left, right int64
 	av := reflect.ValueOf(a)
@@ -96,7 +107,9 @@ func Gt(a interface{}, b interface{}) bool {
 	return left > right
 }
 
-//Eq takes two types and checks whether they are equal. Supported types are int and string. Unsupported types will panic.
+// FIXME Eq is unused by cobra and should be removed in a version 2. It exists only for compatibility with users of cobra.
+
+// Eq takes two types and checks whether they are equal. Supported types are int and string. Unsupported types will panic.
 func Eq(a interface{}, b interface{}) bool {
 	av := reflect.ValueOf(a)
 	bv := reflect.ValueOf(b)
@@ -116,7 +129,9 @@ func trimRightSpace(s string) string {
 	return strings.TrimRightFunc(s, unicode.IsSpace)
 }
 
-// appendIfNotPresent will append stringToAppend to the end of s, but only if it's not yet present in s
+// FIXME appendIfNotPresent is unused by cobra and should be removed in a version 2. It exists only for compatibility with users of cobra.
+
+// appendIfNotPresent will append stringToAppend to the end of s, but only if it's not yet present in s.
 func appendIfNotPresent(s, stringToAppend string) string {
 	if strings.Contains(s, stringToAppend) {
 		return s
@@ -124,7 +139,7 @@ func appendIfNotPresent(s, stringToAppend string) string {
 	return s + " " + stringToAppend
 }
 
-//rpad adds padding to the right of a string
+// rpad adds padding to the right of a string.
 func rpad(s string, padding int) string {
 	template := fmt.Sprintf("%%-%ds", padding)
 	return fmt.Sprintf(template, s)
@@ -138,7 +153,7 @@ func tmpl(w io.Writer, text string, data interface{}) error {
 	return t.Execute(w, data)
 }
 
-// ld compares two strings and returns the levenshtein distance between them
+// ld compares two strings and returns the levenshtein distance between them.
 func ld(s, t string, ignoreCase bool) int {
 	if ignoreCase {
 		s = strings.ToLower(s)
@@ -173,3 +188,12 @@ func ld(s, t string, ignoreCase bool) int {
 	}
 	return d[len(s)][len(t)]
 }
+
+func stringInSlice(a string, list []string) bool {
+	for _, b := range list {
+		if b == a {
+			return true
+		}
+	}
+	return false
+}

vendor/github.com/spf13/cobra/command_win.go

@@ -11,14 +11,8 @@ import (
 
 var preExecHookFn = preExecHook
 
-// enables an information splash screen on Windows if the CLI is started from explorer.exe.
-var MousetrapHelpText string = `This is a command line tool
-
-You need to open cmd.exe and run it from there.
-`
-
 func preExecHook(c *Command) {
-	if mousetrap.StartedByExplorer() {
+	if MousetrapHelpText != "" && mousetrap.StartedByExplorer() {
 		c.Print(MousetrapHelpText)
 		time.Sleep(5 * time.Second)
 		os.Exit(1)

vendor/github.com/spf13/cobra/doc/BUILD

@@ -5,7 +5,9 @@ go_library(
     srcs = [
         "man_docs.go",
         "md_docs.go",
+        "rest_docs.go",
         "util.go",
+        "yaml_docs.go",
     ],
     importpath = "github.com/spf13/cobra/doc",
     visibility = ["//visibility:public"],
@@ -13,6 +15,7 @@ go_library(
         "//vendor/github.com/cpuguy83/go-md2man/md2man:go_default_library",
         "//vendor/github.com/spf13/cobra:go_default_library",
         "//vendor/github.com/spf13/pflag:go_default_library",
+        "//vendor/gopkg.in/yaml.v2:go_default_library",
     ],
 )
 

vendor/github.com/spf13/cobra/doc/man_docs.go

@@ -23,21 +23,21 @@ import (
 	"strings"
 	"time"
 
-	mangen "github.com/cpuguy83/go-md2man/md2man"
+	"github.com/cpuguy83/go-md2man/md2man"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
 // GenManTree will generate a man page for this command and all descendants
 // in the directory given. The header may be nil. This function may not work
-// correctly if your command names have - in them. If you have `cmd` with two
-// subcmds, `sub` and `sub-third`. And `sub` has a subcommand called `third`
+// correctly if your command names have `-` in them. If you have `cmd` with two
+// subcmds, `sub` and `sub-third`, and `sub` has a subcommand called `third`
 // it is undefined which help output will be in the file `cmd-sub-third.1`.
 func GenManTree(cmd *cobra.Command, header *GenManHeader, dir string) error {
 	return GenManTreeFromOpts(cmd, GenManTreeOptions{
 		Header:           header,
 		Path:             dir,
-		CommandSeparator: "_",
+		CommandSeparator: "-",
 	})
 }
 
@@ -49,7 +49,7 @@ func GenManTreeFromOpts(cmd *cobra.Command, opts GenManTreeOptions) error {
 		header = &GenManHeader{}
 	}
 	for _, c := range cmd.Commands() {
-		if !c.IsAvailableCommand() || c.IsHelpCommand() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
 		if err := GenManTreeFromOpts(c, opts); err != nil {
@@ -66,7 +66,7 @@ func GenManTreeFromOpts(cmd *cobra.Command, opts GenManTreeOptions) error {
 		separator = opts.CommandSeparator
 	}
 	basename := strings.Replace(cmd.CommandPath(), " ", separator, -1)
-	filename := filepath.Join(opts.Path, basename + "." + section)
+	filename := filepath.Join(opts.Path, basename+"."+section)
 	f, err := os.Create(filename)
 	if err != nil {
 		return err
@@ -77,6 +77,8 @@ func GenManTreeFromOpts(cmd *cobra.Command, opts GenManTreeOptions) error {
 	return GenMan(cmd, &headerCopy, f)
 }
 
+// GenManTreeOptions is the options for generating the man pages.
+// Used only in GenManTreeFromOpts.
 type GenManTreeOptions struct {
 	Header           *GenManHeader
 	Path             string
@@ -105,7 +107,7 @@ func GenMan(cmd *cobra.Command, header *GenManHeader, w io.Writer) error {
 	fillHeader(header, cmd.CommandPath())
 
 	b := genMan(cmd, header)
-	_, err := w.Write(mangen.Render(b))
+	_, err := w.Write(md2man.Render(b))
 	return err
 }
 
@@ -126,25 +128,25 @@ func fillHeader(header *GenManHeader, name string) {
 	}
 }
 
-func manPreamble(out io.Writer, header *GenManHeader, cmd *cobra.Command, dashedName string) {
+func manPreamble(buf *bytes.Buffer, header *GenManHeader, cmd *cobra.Command, dashedName string) {
 	description := cmd.Long
 	if len(description) == 0 {
 		description = cmd.Short
 	}
 
-	fmt.Fprintf(out, `%% %s(%s)%s
+	buf.WriteString(fmt.Sprintf(`%% %s(%s)%s
 %% %s
 %% %s
 # NAME
-`, header.Title, header.Section, header.date, header.Source, header.Manual)
-	fmt.Fprintf(out, "%s \\- %s\n\n", dashedName, cmd.Short)
-	fmt.Fprintf(out, "# SYNOPSIS\n")
-	fmt.Fprintf(out, "**%s**\n\n", cmd.UseLine())
-	fmt.Fprintf(out, "# DESCRIPTION\n")
-	fmt.Fprintf(out, "%s\n\n", description)
+`, header.Title, header.Section, header.date, header.Source, header.Manual))
+	buf.WriteString(fmt.Sprintf("%s \\- %s\n\n", dashedName, cmd.Short))
+	buf.WriteString("# SYNOPSIS\n")
+	buf.WriteString(fmt.Sprintf("**%s**\n\n", cmd.UseLine()))
+	buf.WriteString("# DESCRIPTION\n")
+	buf.WriteString(description + "\n\n")
 }
 
-func manPrintFlags(out io.Writer, flags *pflag.FlagSet) {
+func manPrintFlags(buf *bytes.Buffer, flags *pflag.FlagSet) {
 	flags.VisitAll(func(flag *pflag.Flag) {
 		if len(flag.Deprecated) > 0 || flag.Hidden {
 			return
@@ -156,38 +158,41 @@ func manPrintFlags(out io.Writer, flags *pflag.FlagSet) {
 			format = fmt.Sprintf("**--%s**", flag.Name)
 		}
 		if len(flag.NoOptDefVal) > 0 {
-			format = format + "["
+			format += "["
 		}
 		if flag.Value.Type() == "string" {
 			// put quotes on the value
-			format = format + "=%q"
+			format += "=%q"
 		} else {
-			format = format + "=%s"
+			format += "=%s"
 		}
 		if len(flag.NoOptDefVal) > 0 {
-			format = format + "]"
+			format += "]"
 		}
-		format = format + "\n\t%s\n\n"
-		fmt.Fprintf(out, format, flag.DefValue, flag.Usage)
+		format += "\n\t%s\n\n"
+		buf.WriteString(fmt.Sprintf(format, flag.DefValue, flag.Usage))
 	})
 }
 
-func manPrintOptions(out io.Writer, command *cobra.Command) {
+func manPrintOptions(buf *bytes.Buffer, command *cobra.Command) {
 	flags := command.NonInheritedFlags()
 	if flags.HasFlags() {
-		fmt.Fprintf(out, "# OPTIONS\n")
-		manPrintFlags(out, flags)
-		fmt.Fprintf(out, "\n")
+		buf.WriteString("# OPTIONS\n")
+		manPrintFlags(buf, flags)
+		buf.WriteString("\n")
 	}
 	flags = command.InheritedFlags()
 	if flags.HasFlags() {
-		fmt.Fprintf(out, "# OPTIONS INHERITED FROM PARENT COMMANDS\n")
-		manPrintFlags(out, flags)
-		fmt.Fprintf(out, "\n")
+		buf.WriteString("# OPTIONS INHERITED FROM PARENT COMMANDS\n")
+		manPrintFlags(buf, flags)
+		buf.WriteString("\n")
 	}
 }
 
 func genMan(cmd *cobra.Command, header *GenManHeader) []byte {
+	cmd.InitDefaultHelpCmd()
+	cmd.InitDefaultHelpFlag()
+
 	// something like `rootcmd-subcmd1-subcmd2`
 	dashCommandName := strings.Replace(cmd.CommandPath(), " ", "-", -1)
 
@@ -196,11 +201,11 @@ func genMan(cmd *cobra.Command, header *GenManHeader) []byte {
 	manPreamble(buf, header, cmd, dashCommandName)
 	manPrintOptions(buf, cmd)
 	if len(cmd.Example) > 0 {
-		fmt.Fprintf(buf, "# EXAMPLE\n")
-		fmt.Fprintf(buf, "```\n%s\n```\n", cmd.Example)
+		buf.WriteString("# EXAMPLE\n")
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n", cmd.Example))
 	}
 	if hasSeeAlso(cmd) {
-		fmt.Fprintf(buf, "# SEE ALSO\n")
+		buf.WriteString("# SEE ALSO\n")
 		seealsos := make([]string, 0)
 		if cmd.HasParent() {
 			parentPath := cmd.Parent().CommandPath()
@@ -216,16 +221,16 @@ func genMan(cmd *cobra.Command, header *GenManHeader) []byte {
 		children := cmd.Commands()
 		sort.Sort(byName(children))
 		for _, c := range children {
-			if !c.IsAvailableCommand() || c.IsHelpCommand() {
+			if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 				continue
 			}
 			seealso := fmt.Sprintf("**%s-%s(%s)**", dashCommandName, c.Name(), header.Section)
 			seealsos = append(seealsos, seealso)
 		}
-		fmt.Fprintf(buf, "%s\n", strings.Join(seealsos, ", "))
+		buf.WriteString(strings.Join(seealsos, ", ") + "\n")
 	}
 	if !cmd.DisableAutoGenTag {
-		fmt.Fprintf(buf, "# HISTORY\n%s Auto generated by spf13/cobra\n", header.Date.Format("2-Jan-2006"))
+		buf.WriteString(fmt.Sprintf("# HISTORY\n%s Auto generated by spf13/cobra\n", header.Date.Format("2-Jan-2006")))
 	}
 	return buf.Bytes()
 }

vendor/github.com/spf13/cobra/doc/man_docs.md

@@ -6,6 +6,8 @@ Generating man pages from a cobra command is incredibly easy. An example is as f
 package main
 
 import (
+	"log"
+
 	"github.com/spf13/cobra"
 	"github.com/spf13/cobra/doc"
 )
@@ -15,12 +17,15 @@ func main() {
 		Use:   "test",
 		Short: "my test program",
 	}
-	header := &cobra.GenManHeader{
+	header := &doc.GenManHeader{
 		Title: "MINE",
 		Section: "3",
 	}
-	doc.GenManTree(cmd, header, "/tmp")
+	err := doc.GenManTree(cmd, header, "/tmp")
+	if err != nil {
+		log.Fatal(err)
+	}
 }
 ```
 
-That will get you a man page `/tmp/test.1`
+That will get you a man page `/tmp/test.3`

vendor/github.com/spf13/cobra/doc/md_docs.go

@@ -14,6 +14,7 @@
 package doc
 
 import (
+	"bytes"
 	"fmt"
 	"io"
 	"os"
@@ -25,38 +26,36 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func printOptions(w io.Writer, cmd *cobra.Command, name string) error {
+func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
 	flags := cmd.NonInheritedFlags()
-	flags.SetOutput(w)
+	flags.SetOutput(buf)
 	if flags.HasFlags() {
-		if _, err := fmt.Fprintf(w, "### Options\n\n```\n"); err != nil {
-			return err
-		}
+		buf.WriteString("### Options\n\n```\n")
 		flags.PrintDefaults()
-		if _, err := fmt.Fprintf(w, "```\n\n"); err != nil {
-			return err
-		}
+		buf.WriteString("```\n\n")
 	}
 
 	parentFlags := cmd.InheritedFlags()
-	parentFlags.SetOutput(w)
+	parentFlags.SetOutput(buf)
 	if parentFlags.HasFlags() {
-		if _, err := fmt.Fprintf(w, "### Options inherited from parent commands\n\n```\n"); err != nil {
-			return err
-		}
+		buf.WriteString("### Options inherited from parent commands\n\n```\n")
 		parentFlags.PrintDefaults()
-		if _, err := fmt.Fprintf(w, "```\n\n"); err != nil {
-			return err
-		}
+		buf.WriteString("```\n\n")
 	}
 	return nil
 }
 
+// GenMarkdown creates markdown output.
 func GenMarkdown(cmd *cobra.Command, w io.Writer) error {
 	return GenMarkdownCustom(cmd, w, func(s string) string { return s })
 }
 
+// GenMarkdownCustom creates custom markdown output.
 func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
+	cmd.InitDefaultHelpCmd()
+	cmd.InitDefaultHelpFlag()
+
+	buf := new(bytes.Buffer)
 	name := cmd.CommandPath()
 
 	short := cmd.Short
@@ -65,49 +64,31 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 		long = short
 	}
 
-	if _, err := fmt.Fprintf(w, "## %s\n\n", name); err != nil {
-		return err
-	}
-	if _, err := fmt.Fprintf(w, "%s\n\n", short); err != nil {
-		return err
-	}
-	if _, err := fmt.Fprintf(w, "### Synopsis\n\n"); err != nil {
-		return err
-	}
-	if _, err := fmt.Fprintf(w, "\n%s\n\n", long); err != nil {
-		return err
-	}
+	buf.WriteString("## " + name + "\n\n")
+	buf.WriteString(short + "\n\n")
+	buf.WriteString("### Synopsis\n\n")
+	buf.WriteString("\n" + long + "\n\n")
 
 	if cmd.Runnable() {
-		if _, err := fmt.Fprintf(w, "```\n%s\n```\n\n", cmd.UseLine()); err != nil {
-			return err
-		}
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine()))
 	}
 
 	if len(cmd.Example) > 0 {
-		if _, err := fmt.Fprintf(w, "### Examples\n\n"); err != nil {
-			return err
-		}
-		if _, err := fmt.Fprintf(w, "```\n%s\n```\n\n", cmd.Example); err != nil {
-			return err
-		}
+		buf.WriteString("### Examples\n\n")
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example))
 	}
 
-	if err := printOptions(w, cmd, name); err != nil {
+	if err := printOptions(buf, cmd, name); err != nil {
 		return err
 	}
 	if hasSeeAlso(cmd) {
-		if _, err := fmt.Fprintf(w, "### SEE ALSO\n"); err != nil {
-			return err
-		}
+		buf.WriteString("### SEE ALSO\n")
 		if cmd.HasParent() {
 			parent := cmd.Parent()
 			pname := parent.CommandPath()
 			link := pname + ".md"
 			link = strings.Replace(link, " ", "_", -1)
-			if _, err := fmt.Fprintf(w, "* [%s](%s)\t - %s\n", pname, linkHandler(link), parent.Short); err != nil {
-				return err
-			}
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", pname, linkHandler(link), parent.Short))
 			cmd.VisitParents(func(c *cobra.Command) {
 				if c.DisableAutoGenTag {
 					cmd.DisableAutoGenTag = c.DisableAutoGenTag
@@ -119,37 +100,40 @@ func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string)
 		sort.Sort(byName(children))
 
 		for _, child := range children {
-			if !child.IsAvailableCommand() || child.IsHelpCommand() {
+			if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
 				continue
 			}
 			cname := name + " " + child.Name()
 			link := cname + ".md"
 			link = strings.Replace(link, " ", "_", -1)
-			if _, err := fmt.Fprintf(w, "* [%s](%s)\t - %s\n", cname, linkHandler(link), child.Short); err != nil {
-				return err
-			}
-		}
-		if _, err := fmt.Fprintf(w, "\n"); err != nil {
-			return err
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", cname, linkHandler(link), child.Short))
 		}
+		buf.WriteString("\n")
 	}
 	if !cmd.DisableAutoGenTag {
-		if _, err := fmt.Fprintf(w, "###### Auto generated by spf13/cobra on %s\n", time.Now().Format("2-Jan-2006")); err != nil {
-			return err
-		}
+		buf.WriteString("###### Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "\n")
 	}
-	return nil
+	_, err := buf.WriteTo(w)
+	return err
 }
 
+// GenMarkdownTree will generate a markdown page for this command and all
+// descendants in the directory given. The header may be nil.
+// This function may not work correctly if your command names have `-` in them.
+// If you have `cmd` with two subcmds, `sub` and `sub-third`,
+// and `sub` has a subcommand called `third`, it is undefined which
+// help output will be in the file `cmd-sub-third.1`.
 func GenMarkdownTree(cmd *cobra.Command, dir string) error {
 	identity := func(s string) string { return s }
 	emptyStr := func(s string) string { return "" }
 	return GenMarkdownTreeCustom(cmd, dir, emptyStr, identity)
 }
 
+// GenMarkdownTreeCustom is the the same as GenMarkdownTree, but
+// with custom filePrepender and linkHandler.
 func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
 	for _, c := range cmd.Commands() {
-		if !c.IsAvailableCommand() || c.IsHelpCommand() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
 		if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil {

vendor/github.com/spf13/cobra/doc/md_docs.md

@@ -6,6 +6,8 @@ Generating man pages from a cobra command is incredibly easy. An example is as f
 package main
 
 import (
+	"log"
+
 	"github.com/spf13/cobra"
 	"github.com/spf13/cobra/doc"
 )
@@ -15,7 +17,10 @@ func main() {
 		Use:   "test",
 		Short: "my test program",
 	}
-	doc.GenMarkdownTree(cmd, "/tmp")
+	err := doc.GenMarkdownTree(cmd, "/tmp")
+	if err != nil {
+		log.Fatal(err)
+	}
 }
 ```
 
@@ -29,18 +34,22 @@ This program can actually generate docs for the kubectl command in the kubernete
 package main
 
 import (
+	"log"
 	"io/ioutil"
 	"os"
 
-	kubectlcmd "k8s.io/kubernetes/pkg/kubectl/cmd"
+	"k8s.io/kubernetes/pkg/kubectl/cmd"
 	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
 
 	"github.com/spf13/cobra/doc"
 )
 
 func main() {
-	cmd := kubectlcmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
-	doc.GenMarkdownTree(cmd, "./")
+	kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
+	err := doc.GenMarkdownTree(kubectl, "./")
+	if err != nil {
+		log.Fatal(err)
+	}
 }
 ```
 
@@ -52,7 +61,10 @@ You may wish to have more control over the output, or only generate for a single
 
 ```go
 	out := new(bytes.Buffer)
-	doc.GenMarkdown(cmd, out)
+	err := doc.GenMarkdown(cmd, out)
+	if err != nil {
+		log.Fatal(err)
+	}
 ```
 
 This will write the markdown doc for ONLY "cmd" into the out, buffer.
@@ -101,4 +113,3 @@ linkHandler := func(name string) string {
 	return "/commands/" + strings.ToLower(base) + "/"
 }
 ```
-

vendor/github.com/spf13/cobra/doc/rest_docs.go

+//Copyright 2015 Red Hat Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package doc
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+func printOptionsReST(buf *bytes.Buffer, cmd *cobra.Command, name string) error {
+	flags := cmd.NonInheritedFlags()
+	flags.SetOutput(buf)
+	if flags.HasFlags() {
+		buf.WriteString("Options\n")
+		buf.WriteString("~~~~~~~\n\n::\n\n")
+		flags.PrintDefaults()
+		buf.WriteString("\n")
+	}
+
+	parentFlags := cmd.InheritedFlags()
+	parentFlags.SetOutput(buf)
+	if parentFlags.HasFlags() {
+		buf.WriteString("Options inherited from parent commands\n")
+		buf.WriteString("~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n")
+		parentFlags.PrintDefaults()
+		buf.WriteString("\n")
+	}
+	return nil
+}
+
+// linkHandler for default ReST hyperlink markup
+func defaultLinkHandler(name, ref string) string {
+	return fmt.Sprintf("`%s <%s.rst>`_", name, ref)
+}
+
+// GenReST creates reStructured Text output.
+func GenReST(cmd *cobra.Command, w io.Writer) error {
+	return GenReSTCustom(cmd, w, defaultLinkHandler)
+}
+
+// GenReSTCustom creates custom reStructured Text output.
+func GenReSTCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string, string) string) error {
+	cmd.InitDefaultHelpCmd()
+	cmd.InitDefaultHelpFlag()
+
+	buf := new(bytes.Buffer)
+	name := cmd.CommandPath()
+
+	short := cmd.Short
+	long := cmd.Long
+	if len(long) == 0 {
+		long = short
+	}
+	ref := strings.Replace(name, " ", "_", -1)
+
+	buf.WriteString(".. _" + ref + ":\n\n")
+	buf.WriteString(name + "\n")
+	buf.WriteString(strings.Repeat("-", len(name)) + "\n\n")
+	buf.WriteString(short + "\n\n")
+	buf.WriteString("Synopsis\n")
+	buf.WriteString("~~~~~~~~\n\n")
+	buf.WriteString("\n" + long + "\n\n")
+
+	if cmd.Runnable() {
+		buf.WriteString(fmt.Sprintf("::\n\n  %s\n\n", cmd.UseLine()))
+	}
+
+	if len(cmd.Example) > 0 {
+		buf.WriteString("Examples\n")
+		buf.WriteString("~~~~~~~~\n\n")
+		buf.WriteString(fmt.Sprintf("::\n\n%s\n\n", indentString(cmd.Example, "  ")))
+	}
+
+	if err := printOptionsReST(buf, cmd, name); err != nil {
+		return err
+	}
+	if hasSeeAlso(cmd) {
+		buf.WriteString("SEE ALSO\n")
+		buf.WriteString("~~~~~~~~\n\n")
+		if cmd.HasParent() {
+			parent := cmd.Parent()
+			pname := parent.CommandPath()
+			ref = strings.Replace(pname, " ", "_", -1)
+			buf.WriteString(fmt.Sprintf("* %s \t - %s\n", linkHandler(pname, ref), parent.Short))
+			cmd.VisitParents(func(c *cobra.Command) {
+				if c.DisableAutoGenTag {
+					cmd.DisableAutoGenTag = c.DisableAutoGenTag
+				}
+			})
+		}
+
+		children := cmd.Commands()
+		sort.Sort(byName(children))
+
+		for _, child := range children {
+			if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
+				continue
+			}
+			cname := name + " " + child.Name()
+			ref = strings.Replace(cname, " ", "_", -1)
+			buf.WriteString(fmt.Sprintf("* %s \t - %s\n", linkHandler(cname, ref), child.Short))
+		}
+		buf.WriteString("\n")
+	}
+	if !cmd.DisableAutoGenTag {
+		buf.WriteString("*Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "*\n")
+	}
+	_, err := buf.WriteTo(w)
+	return err
+}
+
+// GenReSTTree will generate a ReST page for this command and all
+// descendants in the directory given.
+// This function may not work correctly if your command names have `-` in them.
+// If you have `cmd` with two subcmds, `sub` and `sub-third`,
+// and `sub` has a subcommand called `third`, it is undefined which
+// help output will be in the file `cmd-sub-third.1`.
+func GenReSTTree(cmd *cobra.Command, dir string) error {
+	emptyStr := func(s string) string { return "" }
+	return GenReSTTreeCustom(cmd, dir, emptyStr, defaultLinkHandler)
+}
+
+// GenReSTTreeCustom is the the same as GenReSTTree, but
+// with custom filePrepender and linkHandler.
+func GenReSTTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string) string, linkHandler func(string, string) string) error {
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		if err := GenReSTTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
+			return err
+		}
+	}
+
+	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".rst"
+	filename := filepath.Join(dir, basename)
+	f, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
+		return err
+	}
+	if err := GenReSTCustom(cmd, f, linkHandler); err != nil {
+		return err
+	}
+	return nil
+}
+
+// adapted from: https://github.com/kr/text/blob/main/indent.go
+func indentString(s, p string) string {
+	var res []byte
+	b := []byte(s)
+	prefix := []byte(p)
+	bol := true
+	for _, c := range b {
+		if bol && c != '\n' {
+			res = append(res, prefix...)
+		}
+		res = append(res, c)
+		bol = c == '\n'
+	}
+	return string(res)
+}

vendor/github.com/spf13/cobra/doc/rest_docs.md

+# Generating ReStructured Text Docs For Your Own cobra.Command
+
+Generating ReST pages from a cobra command is incredibly easy. An example is as follows:
+
+```go
+package main
+
+import (
+	"log"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	cmd := &cobra.Command{
+		Use:   "test",
+		Short: "my test program",
+	}
+	err := doc.GenReSTTree(cmd, "/tmp")
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+That will get you a ReST document `/tmp/test.rst`
+
+## Generate ReST docs for the entire command tree
+
+This program can actually generate docs for the kubectl command in the kubernetes project
+
+```go
+package main
+
+import (
+	"log"
+	"io/ioutil"
+	"os"
+
+	"k8s.io/kubernetes/pkg/kubectl/cmd"
+	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
+
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
+	err := doc.GenReSTTree(kubectl, "./")
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
+
+## Generate ReST docs for a single command
+
+You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenReST` instead of `GenReSTTree`
+
+```go
+	out := new(bytes.Buffer)
+	err := doc.GenReST(cmd, out)
+	if err != nil {
+		log.Fatal(err)
+	}
+```
+
+This will write the ReST doc for ONLY "cmd" into the out, buffer.
+
+## Customize the output
+
+Both `GenReST` and `GenReSTTree` have alternate versions with callbacks to get some control of the output:
+
+```go
+func GenReSTTreeCustom(cmd *Command, dir string, filePrepender func(string) string, linkHandler func(string, string) string) error {
+	//...
+}
+```
+
+```go
+func GenReSTCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string, string) string) error {
+	//...
+}
+```
+
+The `filePrepender` will prepend the return value given the full filepath to the rendered ReST file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/):
+
+```go
+const fmTemplate = `---
+date: %s
+title: "%s"
+slug: %s
+url: %s
+---
+`
+filePrepender := func(filename string) string {
+	now := time.Now().Format(time.RFC3339)
+	name := filepath.Base(filename)
+	base := strings.TrimSuffix(name, path.Ext(name))
+	url := "/commands/" + strings.ToLower(base) + "/"
+	return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
+}
+```
+
+The `linkHandler` can be used to customize the rendered links to the commands, given a command name and reference. This is useful while converting rst to html or while generating documentation with tools like Sphinx where `:ref:` is used:
+
+```go
+// Sphinx cross-referencing format
+linkHandler := func(name, ref string) string {
+    return fmt.Sprintf(":ref:`%s <%s>`", name, ref)
+}
+```

vendor/github.com/spf13/cobra/doc/util.go

@@ -13,7 +13,11 @@
 
 package doc
 
-import "github.com/spf13/cobra"
+import (
+	"strings"
+
+	"github.com/spf13/cobra"
+)
 
 // Test to see if we have a reason to print See Also information in docs
 // Basically this is a test for a parent commend or a subcommand which is
@@ -23,7 +27,7 @@ func hasSeeAlso(cmd *cobra.Command) bool {
 		return true
 	}
 	for _, c := range cmd.Commands() {
-		if !c.IsAvailableCommand() || c.IsHelpCommand() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
 			continue
 		}
 		return true
@@ -31,6 +35,15 @@ func hasSeeAlso(cmd *cobra.Command) bool {
 	return false
 }
 
+// Temporary workaround for yaml lib generating incorrect yaml with long strings
+// that do not contain \n.
+func forceMultiLine(s string) string {
+	if len(s) > 60 && !strings.Contains(s, "\n") {
+		s = s + "\n"
+	}
+	return s
+}
+
 type byName []*cobra.Command
 
 func (s byName) Len() int           { return len(s) }

vendor/github.com/spf13/cobra/doc/yaml_docs.go

+// Copyright 2016 French Ben. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package doc
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"gopkg.in/yaml.v2"
+)
+
+type cmdOption struct {
+	Name         string
+	Shorthand    string `yaml:",omitempty"`
+	DefaultValue string `yaml:"default_value,omitempty"`
+	Usage        string `yaml:",omitempty"`
+}
+
+type cmdDoc struct {
+	Name             string
+	Synopsis         string      `yaml:",omitempty"`
+	Description      string      `yaml:",omitempty"`
+	Options          []cmdOption `yaml:",omitempty"`
+	InheritedOptions []cmdOption `yaml:"inherited_options,omitempty"`
+	Example          string      `yaml:",omitempty"`
+	SeeAlso          []string    `yaml:"see_also,omitempty"`
+}
+
+// GenYamlTree creates yaml structured ref files for this command and all descendants
+// in the directory given. This function may not work
+// correctly if your command names have `-` in them. If you have `cmd` with two
+// subcmds, `sub` and `sub-third`, and `sub` has a subcommand called `third`
+// it is undefined which help output will be in the file `cmd-sub-third.1`.
+func GenYamlTree(cmd *cobra.Command, dir string) error {
+	identity := func(s string) string { return s }
+	emptyStr := func(s string) string { return "" }
+	return GenYamlTreeCustom(cmd, dir, emptyStr, identity)
+}
+
+// GenYamlTreeCustom creates yaml structured ref files.
+func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		if err := GenYamlTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
+			return err
+		}
+	}
+
+	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".yaml"
+	filename := filepath.Join(dir, basename)
+	f, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	if _, err := io.WriteString(f, filePrepender(filename)); err != nil {
+		return err
+	}
+	if err := GenYamlCustom(cmd, f, linkHandler); err != nil {
+		return err
+	}
+	return nil
+}
+
+// GenYaml creates yaml output.
+func GenYaml(cmd *cobra.Command, w io.Writer) error {
+	return GenYamlCustom(cmd, w, func(s string) string { return s })
+}
+
+// GenYamlCustom creates custom yaml output.
+func GenYamlCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
+	cmd.InitDefaultHelpCmd()
+	cmd.InitDefaultHelpFlag()
+
+	yamlDoc := cmdDoc{}
+	yamlDoc.Name = cmd.CommandPath()
+
+	yamlDoc.Synopsis = forceMultiLine(cmd.Short)
+	yamlDoc.Description = forceMultiLine(cmd.Long)
+
+	if len(cmd.Example) > 0 {
+		yamlDoc.Example = cmd.Example
+	}
+
+	flags := cmd.NonInheritedFlags()
+	if flags.HasFlags() {
+		yamlDoc.Options = genFlagResult(flags)
+	}
+	flags = cmd.InheritedFlags()
+	if flags.HasFlags() {
+		yamlDoc.InheritedOptions = genFlagResult(flags)
+	}
+
+	if hasSeeAlso(cmd) {
+		result := []string{}
+		if cmd.HasParent() {
+			parent := cmd.Parent()
+			result = append(result, parent.CommandPath()+" - "+parent.Short)
+		}
+		children := cmd.Commands()
+		sort.Sort(byName(children))
+		for _, child := range children {
+			if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
+				continue
+			}
+			result = append(result, child.Name()+" - "+child.Short)
+		}
+		yamlDoc.SeeAlso = result
+	}
+
+	final, err := yaml.Marshal(&yamlDoc)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+
+	if _, err := w.Write(final); err != nil {
+		return err
+	}
+	return nil
+}
+
+func genFlagResult(flags *pflag.FlagSet) []cmdOption {
+	var result []cmdOption
+
+	flags.VisitAll(func(flag *pflag.Flag) {
+		// Todo, when we mark a shorthand is deprecated, but specify an empty message.
+		// The flag.ShorthandDeprecated is empty as the shorthand is deprecated.
+		// Using len(flag.ShorthandDeprecated) > 0 can't handle this, others are ok.
+		if !(len(flag.ShorthandDeprecated) > 0) && len(flag.Shorthand) > 0 {
+			opt := cmdOption{
+				flag.Name,
+				flag.Shorthand,
+				flag.DefValue,
+				forceMultiLine(flag.Usage),
+			}
+			result = append(result, opt)
+		} else {
+			opt := cmdOption{
+				Name:         flag.Name,
+				DefaultValue: forceMultiLine(flag.DefValue),
+				Usage:        forceMultiLine(flag.Usage),
+			}
+			result = append(result, opt)
+		}
+	})
+
+	return result
+}

vendor/github.com/spf13/cobra/doc/yaml_docs.md

+# Generating Yaml Docs For Your Own cobra.Command
+
+Generating yaml files from a cobra command is incredibly easy. An example is as follows:
+
+```go
+package main
+
+import (
+	"log"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	cmd := &cobra.Command{
+		Use:   "test",
+		Short: "my test program",
+	}
+	err := doc.GenYamlTree(cmd, "/tmp")
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+That will get you a Yaml document `/tmp/test.yaml`
+
+## Generate yaml docs for the entire command tree
+
+This program can actually generate docs for the kubectl command in the kubernetes project
+
+```go
+package main
+
+import (
+	"io/ioutil"
+	"log"
+	"os"
+
+	"k8s.io/kubernetes/pkg/kubectl/cmd"
+	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
+
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard)
+	err := doc.GenYamlTree(kubectl, "./")
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
+
+## Generate yaml docs for a single command
+
+You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenYaml` instead of `GenYamlTree`
+
+```go
+	out := new(bytes.Buffer)
+	doc.GenYaml(cmd, out)
+```
+
+This will write the yaml doc for ONLY "cmd" into the out, buffer.
+
+## Customize the output
+
+Both `GenYaml` and `GenYamlTree` have alternate versions with callbacks to get some control of the output:
+
+```go
+func GenYamlTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
+	//...
+}
+```
+
+```go
+func GenYamlCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
+	//...
+}
+```
+
+The `filePrepender` will prepend the return value given the full filepath to the rendered Yaml file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/):
+
+```go
+const fmTemplate = `---
+date: %s
+title: "%s"
+slug: %s
+url: %s
+---
+`
+
+filePrepender := func(filename string) string {
+	now := time.Now().Format(time.RFC3339)
+	name := filepath.Base(filename)
+	base := strings.TrimSuffix(name, path.Ext(name))
+	url := "/commands/" + strings.ToLower(base) + "/"
+	return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
+}
+```
+
+The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename:
+
+```go
+linkHandler := func(name string) string {
+	base := strings.TrimSuffix(name, path.Ext(name))
+	return "/commands/" + strings.ToLower(base) + "/"
+}
+```

vendor/github.com/spf13/cobra/zsh_completions.go

+package cobra
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+)
+
+// GenZshCompletionFile generates zsh completion file.
+func (c *Command) GenZshCompletionFile(filename string) error {
+	outFile, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	defer outFile.Close()
+
+	return c.GenZshCompletion(outFile)
+}
+
+// GenZshCompletion generates a zsh completion file and writes to the passed writer.
+func (c *Command) GenZshCompletion(w io.Writer) error {
+	buf := new(bytes.Buffer)
+
+	writeHeader(buf, c)
+	maxDepth := maxDepth(c)
+	writeLevelMapping(buf, maxDepth)
+	writeLevelCases(buf, maxDepth, c)
+
+	_, err := buf.WriteTo(w)
+	return err
+}
+
+func writeHeader(w io.Writer, cmd *Command) {
+	fmt.Fprintf(w, "#compdef %s\n\n", cmd.Name())
+}
+
+func maxDepth(c *Command) int {
+	if len(c.Commands()) == 0 {
+		return 0
+	}
+	maxDepthSub := 0
+	for _, s := range c.Commands() {
+		subDepth := maxDepth(s)
+		if subDepth > maxDepthSub {
+			maxDepthSub = subDepth
+		}
+	}
+	return 1 + maxDepthSub
+}
+
+func writeLevelMapping(w io.Writer, numLevels int) {
+	fmt.Fprintln(w, `_arguments \`)
+	for i := 1; i <= numLevels; i++ {
+		fmt.Fprintf(w, `  '%d: :->level%d' \`, i, i)
+		fmt.Fprintln(w)
+	}
+	fmt.Fprintf(w, `  '%d: :%s'`, numLevels+1, "_files")
+	fmt.Fprintln(w)
+}
+
+func writeLevelCases(w io.Writer, maxDepth int, root *Command) {
+	fmt.Fprintln(w, "case $state in")
+	defer fmt.Fprintln(w, "esac")
+
+	for i := 1; i <= maxDepth; i++ {
+		fmt.Fprintf(w, "  level%d)\n", i)
+		writeLevel(w, root, i)
+		fmt.Fprintln(w, "  ;;")
+	}
+	fmt.Fprintln(w, "  *)")
+	fmt.Fprintln(w, "    _arguments '*: :_files'")
+	fmt.Fprintln(w, "  ;;")
+}
+
+func writeLevel(w io.Writer, root *Command, i int) {
+	fmt.Fprintf(w, "    case $words[%d] in\n", i)
+	defer fmt.Fprintln(w, "    esac")
+
+	commands := filterByLevel(root, i)
+	byParent := groupByParent(commands)
+
+	for p, c := range byParent {
+		names := names(c)
+		fmt.Fprintf(w, "      %s)\n", p)
+		fmt.Fprintf(w, "        _arguments '%d: :(%s)'\n", i, strings.Join(names, " "))
+		fmt.Fprintln(w, "      ;;")
+	}
+	fmt.Fprintln(w, "      *)")
+	fmt.Fprintln(w, "        _arguments '*: :_files'")
+	fmt.Fprintln(w, "      ;;")
+
+}
+
+func filterByLevel(c *Command, l int) []*Command {
+	cs := make([]*Command, 0)
+	if l == 0 {
+		cs = append(cs, c)
+		return cs
+	}
+	for _, s := range c.Commands() {
+		cs = append(cs, filterByLevel(s, l-1)...)
+	}
+	return cs
+}
+
+func groupByParent(commands []*Command) map[string][]*Command {
+	m := make(map[string][]*Command)
+	for _, c := range commands {
+		parent := c.Parent()
+		if parent == nil {
+			continue
+		}
+		m[parent.Name()] = append(m[parent.Name()], c)
+	}
+	return m
+}
+
+func names(commands []*Command) []string {
+	ns := make([]string, len(commands))
+	for i, c := range commands {
+		ns[i] = c.Name()
+	}
+	return ns
+}