Merge pull request #4664 from eparis/kubectl-man

kubectl autogen docs update

Godeps/Godeps.json

@@ -250,7 +250,7 @@
 		},
 		{
 			"ImportPath": "github.com/spf13/cobra",
-			"Rev": "07a9dc0024fcc97a0dcb3117bdf8933367037f4e"
+			"Rev": "f8e1ec56bdd7494d309c69681267859a6bfb7549"
 		},
 		{
 			"ImportPath": "github.com/spf13/pflag",

Godeps/_workspace/src/github.com/spf13/cobra/cobra_test.go

@@ -467,8 +467,16 @@ func TestRootHelp(t *testing.T) {
 		t.Errorf("--help shouldn't trigger an error, Got: \n %s", x.Output)
 	}
 
+	if strings.Contains(x.Output, cmdEcho.Use) {
+		t.Errorf("--help shouldn't display subcommand's usage, Got: \n %s", x.Output)
+	}
+
 	x = fullSetupTest("echo --help")
 
+	if strings.Contains(x.Output, cmdTimes.Use) {
+		t.Errorf("--help shouldn't display subsubcommand's usage, Got: \n %s", x.Output)
+	}
+
 	checkResultContains(t, x, "Available Commands:")
 	checkResultContains(t, x, "for more information about a command")
 

Godeps/_workspace/src/github.com/spf13/cobra/command.go

@@ -40,6 +40,8 @@ type Command struct {
 	Short string
 	// The long message shown in the 'help <this-command>' output.
 	Long string
+	// Examples of how to use the command
+	Example string
 	// Full set of flags
 	flags *flag.FlagSet
 	// Set of flags childrens of this command will inherit
@@ -54,6 +56,7 @@ type Command struct {
 	// max lengths of commands' string lengths for use in padding
 	commandsMaxUseLen         int
 	commandsMaxCommandPathLen int
+	commandsMaxNameLen        int
 
 	flagErrorBuf *bytes.Buffer
 	cmdErrorBuf  *bytes.Buffer
@@ -181,6 +184,16 @@ func (c *Command) CommandPathPadding() int {
 	}
 }
 
+var minNamePadding int = 11
+
+func (c *Command) NamePadding() int {
+	if c.parent == nil || minNamePadding > c.parent.commandsMaxNameLen {
+		return minNamePadding
+	} else {
+		return c.parent.commandsMaxNameLen
+	}
+}
+
 func (c *Command) UsageTemplate() string {
 	if c.usageTemplate != "" {
 		return c.usageTemplate
@@ -195,10 +208,13 @@ Usage: {{if .Runnable}}
   {{ .CommandPath}} [command]{{end}}{{if gt .Aliases 0}}
 
 Aliases:
-  {{.NameAndAliases}}{{end}}
-{{ if .HasSubCommands}}
+  {{.NameAndAliases}}
+{{end}}{{if .HasExample}}
+Examples:
+{{ .Example }}
+{{end}}{{ if .HasSubCommands}}
 Available Commands: {{range .Commands}}{{if .Runnable}}
-  {{rpad .Use .UsagePadding }} {{.Short}}{{end}}{{end}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}
 {{end}}
 {{ if .HasLocalFlags}}Flags:
 {{.LocalFlags.FlagUsages}}{{end}}
@@ -529,6 +545,10 @@ func (c *Command) AddCommand(cmds ...*Command) {
 		if commandPathLen > c.commandsMaxCommandPathLen {
 			c.commandsMaxCommandPathLen = commandPathLen
 		}
+		nameLen := len(x.Name())
+		if nameLen > c.commandsMaxNameLen {
+			c.commandsMaxNameLen = nameLen
+		}
 		c.commands = append(c.commands, x)
 	}
 }
@@ -669,6 +689,10 @@ func (c *Command) NameAndAliases() string {
 	return strings.Join(append([]string{c.Name()}, c.Aliases...), ", ")
 }
 
+func (c *Command) HasExample() bool {
+	return len(c.Example) > 0
+}
+
 // Determine if the command is itself runnable
 func (c *Command) Runnable() bool {
 	return c.Run != nil
@@ -713,6 +737,50 @@ func (c *Command) LocalFlags() *flag.FlagSet {
 	return local
 }
 
+// All Flags which were inherited from parents commands
+func (c *Command) InheritedFlags() *flag.FlagSet {
+	c.mergePersistentFlags()
+
+	local := flag.NewFlagSet(c.Name(), flag.ContinueOnError)
+
+        var rmerge func(x *Command)
+
+        rmerge = func(x *Command) {
+                if x.HasPersistentFlags() {
+                        x.PersistentFlags().VisitAll(func(f *flag.Flag) {
+                                if local.Lookup(f.Name) == nil {
+                                        local.AddFlag(f)
+                                }
+                        })
+                }
+                if x.HasParent() {
+                        rmerge(x.parent)
+                }
+        }
+
+	if c.HasParent() {
+		rmerge(c.parent)
+	}
+
+	return local
+}
+
+// All Flags which were not inherited from parent commands
+func (c *Command) NonInheritedFlags() *flag.FlagSet {
+	c.mergePersistentFlags()
+
+	local := flag.NewFlagSet(c.Name(), flag.ContinueOnError)
+	inheritedFlags := c.InheritedFlags()
+
+	c.Flags().VisitAll(func(f *flag.Flag) {
+		if inheritedFlags.Lookup(f.Name) == nil {
+			local.AddFlag(f)
+		}
+	})
+
+	return local
+}
+
 // Get the Persistent FlagSet specifically set in the current command
 func (c *Command) PersistentFlags() *flag.FlagSet {
 	if c.pflags == nil {

cmd/gendocs/gen_kubectl_docs.go

@@ -26,42 +26,10 @@ import (
 
 	"github.com/GoogleCloudPlatform/kubernetes/pkg/kubectl/cmd"
 	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
 )
 
-func mergeFlags(old, newFlags *pflag.FlagSet) *pflag.FlagSet {
-	newFlags.VisitAll(func(f *pflag.Flag) {
-		if old.Lookup(f.Name) == nil {
-			old.AddFlag(f)
-		}
-	})
-	return old
-}
-
-func parentFlags(c *cobra.Command) *pflag.FlagSet {
-	if !c.HasParent() {
-		return pflag.NewFlagSet("empty", pflag.ExitOnError)
-	}
-	return mergeFlags(c.Parent().PersistentFlags(), parentFlags(c.Parent()))
-}
-
-func myFlags(c *cobra.Command) *pflag.FlagSet {
-	myFlags := c.Flags()
-	parentFlags := parentFlags(c)
-
-	if c.HasPersistentFlags() {
-		c.PersistentFlags().VisitAll(func(f *pflag.Flag) {
-			if c.Flags().Lookup(f.Name) == nil &&
-				parentFlags.Lookup(f.Name) == nil {
-				myFlags.AddFlag(f)
-			}
-		})
-	}
-	return myFlags
-}
-
 func printOptions(out *bytes.Buffer, command *cobra.Command, name string) {
-	flags := myFlags(command)
+	flags := command.NonInheritedFlags()
 	flags.SetOutput(out)
 	if command.Runnable() {
 		fmt.Fprintf(out, "%s\n\n", command.UseLine())
@@ -72,7 +40,7 @@ func printOptions(out *bytes.Buffer, command *cobra.Command, name string) {
 		fmt.Fprintf(out, "```\n\n")
 	}
 
-	parentFlags := parentFlags(command)
+	parentFlags := command.InheritedFlags()
 	parentFlags.SetOutput(out)
 	if parentFlags.HasFlags() {
 		fmt.Fprintf(out, "### Options inherrited from parent commands\n\n```\n")

docs/kubectl-config-set-cluster.md

@@ -13,15 +13,6 @@ Sets a cluster entry in .kubeconfig
 
 kubectl config set-cluster name [--server=server] [--certificate-authority=path/to/certficate/authority] [--api-version=apiversion] [--insecure-skip-tls-verify=true]
 
-### Options
-
-```
-      --api-version=: api-version for the cluster entry in .kubeconfig
-      --certificate-authority=: certificate-authority for the cluster entry in .kubeconfig
-      --insecure-skip-tls-verify=false: insecure-skip-tls-verify for the cluster entry in .kubeconfig
-      --server=: server for the cluster entry in .kubeconfig
-```
-
 ### Options inherrited from parent commands
 
 ```

docs/kubectl-config-set-context.md

@@ -13,14 +13,6 @@ Sets a context entry in .kubeconfig
 
 kubectl config set-context name [--cluster=cluster-nickname] [--user=user-nickname] [--namespace=namespace]
 
-### Options
-
-```
-      --cluster=: cluster for the context entry in .kubeconfig
-      --namespace=: namespace for the context entry in .kubeconfig
-      --user=: user for the context entry in .kubeconfig
-```
-
 ### Options inherrited from parent commands
 
 ```

docs/kubectl-config-set-credentials.md

@@ -26,17 +26,6 @@ Sets a user entry in .kubeconfig
 
 kubectl config set-credentials name [--auth-path=authfile] [--client-certificate=certfile] [--client-key=keyfile] [--token=bearer_token] [--username=basic_user] [--password=basic_password]
 
-### Options
-
-```
-      --auth-path=: auth-path for the user entry in .kubeconfig
-      --client-certificate=: client-certificate for the user entry in .kubeconfig
-      --client-key=: client-key for the user entry in .kubeconfig
-      --password=: password for the user entry in .kubeconfig
-      --token=: token for the user entry in .kubeconfig
-      --username=: username for the user entry in .kubeconfig
-```
-
 ### Options inherrited from parent commands
 
 ```