Autogenerate md documentation for kubectl

This does away with the giant dump from cobra for kubectl and instead generates md files which contain similar information, but one per verb. This might work well as part of the cobra project, instead of doing it in kube, but this gets us nice, linked, documentation right now. If people like it, I will try to get something similar into cobra.
duda · Feb 13, 2015 · a6beb2e · a6beb2e
1 parent 9e9fb94
commit a6beb2e
Show file tree

Hide file tree

Showing 32 changed files with 1,550 additions and 1,117 deletions.
diff --git a/cmd/gendocs/gen_kubectl_docs.go b/cmd/gendocs/gen_kubectl_docs.go
@@ -17,42 +17,156 @@ limitations under the License.
 package main
 
 import (
+	"bytes"
 	"fmt"
-	"io"
+	"io/ioutil"
 	"os"
+	"path/filepath"
+	"strings"
 
 	"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.SetOutput(out)
+	if command.Runnable() {
+		fmt.Fprintf(out, "%s\n\n", command.UseLine())
+	}
+	if flags.HasFlags() {
+		fmt.Fprintf(out, "### Options\n\n```\n")
+		flags.PrintDefaults()
+		fmt.Fprintf(out, "```\n\n")
+	}
+
+	parentFlags := parentFlags(command)
+	parentFlags.SetOutput(out)
+	if parentFlags.HasFlags() {
+		fmt.Fprintf(out, "### Options inherrited from parent commands\n\n```\n")
+		parentFlags.PrintDefaults()
+		fmt.Fprintf(out, "```\n\n")
+	}
+}
+
+func genMarkdown(command *cobra.Command, parent, docsDir string) {
+	dparent := strings.Replace(parent, " ", "-", -1)
+	name := command.Name()
+	dname := name
+	if len(parent) > 0 {
+		dname = dparent + "-" + name
+		name = parent + " " + name
+	}
+
+	out := new(bytes.Buffer)
+	short := command.Short
+	long := command.Long
+	if len(long) == 0 {
+		long = short
+	}
+
+	fmt.Fprintf(out, "## %s\n\n", name)
+	fmt.Fprintf(out, "%s\n\n", short)
+	fmt.Fprintf(out, "### Synopsis\n\n")
+	fmt.Fprintf(out, "%s\n\n", long)
+
+	printOptions(out, command, name)
+
+	if len(command.Commands()) > 0 || len(parent) > 0 {
+		fmt.Fprintf(out, "### SEE ALSO\n")
+		if len(parent) > 0 {
+			link := dparent + ".md"
+			fmt.Fprintf(out, "* [%s](%s)\n", dparent, link)
+		}
+		for _, c := range command.Commands() {
+			child := dname + "-" + c.Name()
+			link := child + ".md"
+			fmt.Fprintf(out, "* [%s](%s)\n", child, link)
+			genMarkdown(c, name, docsDir)
+		}
+		fmt.Fprintf(out, "\n")
+	}
+
+	filename := docsDir + dname + ".md"
+	outFile, err := os.Create(filename)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	defer outFile.Close()
+	_, err = outFile.Write(out.Bytes())
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}
+
 func main() {
-	out := os.Stdout
+	// use os.Args instead of "flags" because "flags" will mess up the man pages!
+	docsDir := "docs/man/man1/"
+	if len(os.Args) == 2 {
+		docsDir = os.Args[1]
+	} else if len(os.Args) > 2 {
+		fmt.Fprintf(os.Stderr, "usage: %s [output directory]\n", os.Args[0])
+		return
+	}
+
+	docsDir, err := filepath.Abs(docsDir)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, err.Error())
+		return
+	}
+
+	stat, err := os.Stat(docsDir)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "output directory %s does not exist\n", docsDir)
+		return
+	}
+
+	if !stat.IsDir() {
+		fmt.Fprintf(os.Stderr, "output directory %s is not a directory\n", docsDir)
+		return
+	}
+	docsDir = docsDir + "/"
+
 	// Set environment variables used by kubectl so the output is consistent,
 	// regardless of where we run.
 	os.Setenv("HOME", "/home/username")
-	kubectl := cmd.NewFactory(nil).NewKubectlCommand(out)
-	fmt.Fprintf(out, "## %s\n\n", kubectl.Name())
-	fmt.Fprintf(out, "%s\n\n", kubectl.Short)
-	fmt.Fprintln(out, "### Commands\n")
+	kubectl := cmd.NewFactory(nil).NewKubectlCommand(ioutil.Discard)
+	genMarkdown(kubectl, "", docsDir)
 	for _, c := range kubectl.Commands() {
-		genMarkdown(c, nil, out)
-	}
-}
-
-func genMarkdown(command, parent *cobra.Command, out io.Writer) {
-	name := command.Name()
-	if parent != nil {
-		name = fmt.Sprintf("%s %s", parent.Name(), name)
-	}
-	fmt.Fprintf(out, "#### %s\n", name)
-	desc := command.Long
-	if len(desc) == 0 {
-		desc = command.Short
-	}
-	fmt.Fprintf(out, "%s\n\n", desc)
-	usage := command.UsageString()
-	fmt.Fprintf(out, "Usage:\n```\n%s\n```\n\n", usage[9:len(usage)-1])
-	for _, c := range command.Commands() {
-		genMarkdown(c, command, out)
+		genMarkdown(c, "kubectl", docsDir)
 	}
 }
diff --git a/docs/kubectl-config-set-cluster.md b/docs/kubectl-config-set-cluster.md
@@ -0,0 +1,59 @@
+## kubectl config set-cluster
+
+Sets a cluster entry in .kubeconfig
+
+### Synopsis
+
+Sets a cluster entry in .kubeconfig
+	Specifying a name that already exists will merge new fields on top of existing values for those fields.
+	e.g. 
+		kubectl config set-cluster e2e --certificate-authority=~/.kube/e2e/.kubernetes.ca.cert
+		only sets the certificate-authority field on the e2e cluster entry without touching other values.
+
+
+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
+
+```
+      --alsologtostderr=false: log to standard error as well as files
+      --api-version="": The API version to use when talking to the server
+  -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https.
+      --certificate-authority="": Path to a cert. file for the certificate authority.
+      --client-certificate="": Path to a client key file for TLS.
+      --client-key="": Path to a client key file for TLS.
+      --cluster="": The name of the kubeconfig cluster to use
+      --context="": The name of the kubeconfig context to use
+      --envvar=false: use the .kubeconfig from $KUBECONFIG
+      --global=false: use the .kubeconfig from /home/username
+  -h, --help=false: help for config
+      --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
+      --kubeconfig="": use a particular .kubeconfig file
+      --local=false: use the .kubeconfig in the current directory
+      --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+      --log_dir=: If non-empty, write log files in this directory
+      --log_flush_frequency=5s: Maximum number of seconds between log flushes
+      --logtostderr=true: log to standard error instead of files
+      --match-server-version=false: Require server version to match client version
+      --namespace="": If present, the namespace scope for this CLI request.
+  -s, --server="": The address and port of the Kubernetes API server
+      --stderrthreshold=2: logs at or above this threshold go to stderr
+      --token="": Bearer token for authentication to the API server.
+      --user="": The name of the kubeconfig user to use
+      --v=0: log level for V logs
+      --validate=false: If true, use a schema to validate the input before sending it
+      --vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+```
+
+### SEE ALSO
+* [kubectl-config](kubectl-config.md)
+
diff --git a/docs/kubectl-config-set-context.md b/docs/kubectl-config-set-context.md
@@ -0,0 +1,58 @@
+## kubectl config set-context
+
+Sets a context entry in .kubeconfig
+
+### Synopsis
+
+Sets a context entry in .kubeconfig
+	Specifying a name that already exists will merge new fields on top of existing values for those fields.
+	e.g. 
+		kubectl config set-context gce --user=cluster-admin
+		only sets the user field on the gce context entry without touching other values.
+
+
+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
+
+```
+      --alsologtostderr=false: log to standard error as well as files
+      --api-version="": The API version to use when talking to the server
+  -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https.
+      --certificate-authority="": Path to a cert. file for the certificate authority.
+      --client-certificate="": Path to a client key file for TLS.
+      --client-key="": Path to a client key file for TLS.
+      --cluster="": The name of the kubeconfig cluster to use
+      --context="": The name of the kubeconfig context to use
+      --envvar=false: use the .kubeconfig from $KUBECONFIG
+      --global=false: use the .kubeconfig from /home/username
+  -h, --help=false: help for config
+      --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
+      --kubeconfig="": use a particular .kubeconfig file
+      --local=false: use the .kubeconfig in the current directory
+      --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+      --log_dir=: If non-empty, write log files in this directory
+      --log_flush_frequency=5s: Maximum number of seconds between log flushes
+      --logtostderr=true: log to standard error instead of files
+      --match-server-version=false: Require server version to match client version
+      --namespace="": If present, the namespace scope for this CLI request.
+  -s, --server="": The address and port of the Kubernetes API server
+      --stderrthreshold=2: logs at or above this threshold go to stderr
+      --token="": Bearer token for authentication to the API server.
+      --user="": The name of the kubeconfig user to use
+      --v=0: log level for V logs
+      --validate=false: If true, use a schema to validate the input before sending it
+      --vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+```
+
+### SEE ALSO
+* [kubectl-config](kubectl-config.md)
+
diff --git a/docs/kubectl-config-set-credentials.md b/docs/kubectl-config-set-credentials.md
@@ -0,0 +1,59 @@
+## kubectl config set-credentials
+
+Sets a user entry in .kubeconfig
+
+### Synopsis
+
+Sets a user entry in .kubeconfig
+	Specifying a name that already exists will merge new fields on top of existing values for those fields.
+	e.g. 
+		kubectl config set-credentials cluster-admin --client-key=~/.kube/cluster-admin/.kubecfg.key
+		only sets the client-key field on the cluster-admin user entry without touching other values.
+
+
+kubectl config set-credentials name [--auth-path=path/to/auth/file] [--client-certificate=path/to/certficate/file] [--client-key=path/to/key/file] [--token=bearer_token_string]
+
+### 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
+      --token=: token for the user entry in .kubeconfig
+```
+
+### Options inherrited from parent commands
+
+```
+      --alsologtostderr=false: log to standard error as well as files
+      --api-version="": The API version to use when talking to the server
+  -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https.
+      --certificate-authority="": Path to a cert. file for the certificate authority.
+      --client-certificate="": Path to a client key file for TLS.
+      --client-key="": Path to a client key file for TLS.
+      --cluster="": The name of the kubeconfig cluster to use
+      --context="": The name of the kubeconfig context to use
+      --envvar=false: use the .kubeconfig from $KUBECONFIG
+      --global=false: use the .kubeconfig from /home/username
+  -h, --help=false: help for config
+      --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure.
+      --kubeconfig="": use a particular .kubeconfig file
+      --local=false: use the .kubeconfig in the current directory
+      --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+      --log_dir=: If non-empty, write log files in this directory
+      --log_flush_frequency=5s: Maximum number of seconds between log flushes
+      --logtostderr=true: log to standard error instead of files
+      --match-server-version=false: Require server version to match client version
+      --namespace="": If present, the namespace scope for this CLI request.
+  -s, --server="": The address and port of the Kubernetes API server
+      --stderrthreshold=2: logs at or above this threshold go to stderr
+      --token="": Bearer token for authentication to the API server.
+      --user="": The name of the kubeconfig user to use
+      --v=0: log level for V logs
+      --validate=false: If true, use a schema to validate the input before sending it
+      --vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+```
+
+### SEE ALSO
+* [kubectl-config](kubectl-config.md)
+