more kubectl doc update

cmd/gendocs/gen_kubectl_docs.go

@@ -31,9 +31,6 @@ import (
 func printOptions(out *bytes.Buffer, command *cobra.Command, name string) {
 	flags := command.NonInheritedFlags()
 	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()
@@ -68,7 +65,16 @@ func genMarkdown(command *cobra.Command, parent, docsDir string) {
 	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)
+	fmt.Fprintf(out, "```\n%s\n```\n\n", long)
+
+	if command.Runnable() {
+		fmt.Fprintf(out, "%s\n\n", command.UseLine())
+	}
+
+	if len(command.Example) > 0 {
+		fmt.Fprintf(out, "### Examples\n\n")
+		fmt.Fprintf(out, "```\n%s\n```\n\n", command.Example)
+	}
 
 	printOptions(out, command, name)
 

cmd/genman/gen_kubectl_man.go

@@ -100,18 +100,18 @@ func printFlags(out *bytes.Buffer, flags *pflag.FlagSet) {
 }
 
 func printOptions(out *bytes.Buffer, command *cobra.Command) {
-	var flags *pflag.FlagSet
-	if command.HasFlags() {
-		flags = command.Flags()
-	} else if !command.HasParent() && command.HasPersistentFlags() {
-		flags = command.PersistentFlags()
+	flags := command.NonInheritedFlags()
+	if flags.HasFlags() {
+		fmt.Fprintf(out, "# OPTIONS\n")
+		printFlags(out, flags)
+		fmt.Fprintf(out, "\n")
 	}
-	if flags == nil {
-		return
+	flags = command.InheritedFlags()
+	if flags.HasFlags() {
+		fmt.Fprintf(out, "# OPTIONS INHERITED FROM PARENT COMMANDS\n")
+		printFlags(out, flags)
+		fmt.Fprintf(out, "\n")
 	}
-	fmt.Fprintf(out, "# OPTIONS\n")
-	printFlags(out, flags)
-	fmt.Fprintf(out, "\n")
 }
 
 func genMarkdown(command *cobra.Command, parent, docsDir string) {
@@ -133,6 +133,11 @@ func genMarkdown(command *cobra.Command, parent, docsDir string) {
 	preamble(out, name, short, long)
 	printOptions(out, command)
 
+	if len(command.Example) > 0 {
+		fmt.Fprintf(out, "# EXAMPLE\n")
+		fmt.Fprintf(out, "```\n%s\n```\n", command.Example)
+	}
+
 	if len(command.Commands()) > 0 || len(parent) > 0 {
 		fmt.Fprintf(out, "# SEE ALSO\n")
 		if len(parent) > 0 {

docs/kubectl-config-set-cluster.md

@@ -4,12 +4,14 @@ 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]
 

docs/kubectl-config-set-context.md

@@ -4,12 +4,13 @@ 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]
 

docs/kubectl-config-set-credentials.md

@@ -4,6 +4,7 @@ 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
@@ -23,6 +24,7 @@ Sets a user entry in .kubeconfig
 
   Bearer token and basic auth are mutually exclusive.
 
+```
 
 kubectl config set-credentials name [--auth-path=authfile] [--client-certificate=certfile] [--client-key=keyfile] [--token=bearer_token] [--username=basic_user] [--password=basic_password]
 

docs/kubectl-config-set.md

@@ -4,12 +4,14 @@ Sets an individual value in a .kubeconfig file
 
 ### Synopsis
 
+```
 Sets an individual value in a .kubeconfig file
 
 		property-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
 		property-value is the new value you wish to set.
 
 
+```
 
 kubectl config set property-name property-value
 

docs/kubectl-config-unset.md

@@ -4,10 +4,12 @@ Unsets an individual value in a .kubeconfig file
 
 ### Synopsis
 
+```
 Unsets an individual value in a .kubeconfig file
 
 		property-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
 
+```
 
 kubectl config unset property-name
 

docs/kubectl-config-use-context.md

@@ -4,7 +4,9 @@ Sets the current-context in a .kubeconfig file
 
 ### Synopsis
 
+```
 Sets the current-context in a .kubeconfig file
+```
 
 kubectl config use-context context-name
 

docs/kubectl-config-view.md

@@ -4,16 +4,22 @@ displays merged .kubeconfig settings or a specified .kubeconfig file.
 
 ### Synopsis
 
+```
 displays merged .kubeconfig settings or a specified .kubeconfig file.
-Examples:
-  // Show merged .kubeconfig settings.
-  $ kubectl config view
-
-  // Show only local ./.kubeconfig settings
-  $ kubectl config view --local
+```
 
 kubectl config view
 
+### Examples
+
+```
+// Show merged .kubeconfig settings.
+$ kubectl config view
+
+// Show only local ./.kubeconfig settings
+$ kubectl config view --local
+```
+
 ### Options
 
 ```

docs/kubectl-config.md

@@ -4,7 +4,9 @@ config modifies .kubeconfig files
 
 ### Synopsis
 
+```
 config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context"
+```
 
 kubectl config <subcommand>
 

docs/kubectl-create.md

@@ -4,19 +4,23 @@ Create a resource by filename or stdin
 
 ### Synopsis
 
+```
 Create a resource by filename or stdin.
 
 JSON and YAML formats are accepted.
+```
 
-Examples:
+kubectl create -f filename
 
-    // Create a pod using the data in pod.json.
-    $ kubectl create -f pod.json
+### Examples
 
-    // Create a pod based on the JSON passed into stdin.
-    $ cat pod.json | kubectl create -f -
+```
+// Create a pod using the data in pod.json.
+$ kubectl create -f pod.json
 
-kubectl create -f filename
+// Create a pod based on the JSON passed into stdin.
+$ cat pod.json | kubectl create -f -
+```
 
 ### Options
 

docs/kubectl-delete.md

@@ -4,6 +4,7 @@ Delete a resource by filename, stdin, or resource and ID.
 
 ### Synopsis
 
+```
 Delete a resource by filename, stdin, resource and ID, or by resources and label selector.
 
 JSON and YAML formats are accepted.
@@ -14,25 +15,28 @@ arguments are used and the filename is ignored.
 Note that the delete command does NOT do resource version checks, so if someone
 submits an update to a resource right when you submit a delete, their update
 will be lost along with the rest of the resource.
+```
 
-Examples:
+kubectl delete ([-f filename] | (<resource> [(<id> | -l <label> | --all)]
 
-    // Delete a pod using the type and ID specified in pod.json.
-    $ kubectl delete -f pod.json
+### Examples
 
-    // Delete a pod based on the type and ID in the JSON passed into stdin.
-    $ cat pod.json | kubectl delete -f -
+```
+// Delete a pod using the type and ID specified in pod.json.
+$ kubectl delete -f pod.json
 
-    // Delete pods and services with label name=myLabel.
-    $ kubectl delete pods,services -l name=myLabel
+// Delete a pod based on the type and ID in the JSON passed into stdin.
+$ cat pod.json | kubectl delete -f -
 
-    // Delete a pod with ID 1234-56-7890-234234-456456.
-    $ kubectl delete pod 1234-56-7890-234234-456456
+// Delete pods and services with label name=myLabel.
+$ kubectl delete pods,services -l name=myLabel
 
-    // Delete all pods
-    $ kubectl delete pods --all
+// Delete a pod with ID 1234-56-7890-234234-456456.
+$ kubectl delete pod 1234-56-7890-234234-456456
 
-kubectl delete ([-f filename] | (<resource> [(<id> | -l <label> | --all)]
+// Delete all pods
+$ kubectl delete pods --all
+```
 
 ### Options
 

docs/kubectl-describe.md

@@ -4,10 +4,12 @@ Show details of a specific resource
 
 ### Synopsis
 
+```
 Show details of a specific resource.
 
 This command joins many API calls together to form a detailed description of a
 given resource.
+```
 
 kubectl describe <resource> <id>
 

docs/kubectl-exec.md

@@ -4,17 +4,22 @@ Execute a command in a container.
 
 ### Synopsis
 
+```
 Execute a command in a container.
-Examples:
-  $ kubectl exec -p 123456-7890 -c ruby-container date
-  <returns output from running 'date' in ruby-container from pod 123456-7890>
-
-  $ kubectl exec -p 123456-7890 -c ruby-container -i -t -- bash -il
-  <switches to raw terminal mode, sends stdin to 'bash' in ruby-container from
-   pod 123456-780 and sends stdout/stderr from 'bash' back to the client
+```
 
 kubectl exec -p <pod> -c <container> -- <command> [<args...>]
 
+### Examples
+
+```
+// get output from running 'date' in ruby-container from pod 123456-7890
+$ kubectl exec -p 123456-7890 -c ruby-container date
+
+//switch to raw terminal mode, sends stdin to 'bash' in ruby-container from pod 123456-780 and sends stdout/stderr from 'bash' back to the client
+$ kubectl exec -p 123456-7890 -c ruby-container -i -t -- bash -il
+```
+
 ### Options
 
 ```

docs/kubectl-expose.md

@@ -4,20 +4,24 @@ Take a replicated application and expose it as Kubernetes Service
 
 ### Synopsis
 
+```
 Take a replicated application and expose it as Kubernetes Service.
 
 Looks up a ReplicationController by name, and uses the selector for that replication controller
 as the selector for a new Service on the specified port.
+```
 
-Examples:
+kubectl expose <name> --port=<port> [--protocol=TCP|UDP] [--container-port=<number-or-name>] [--service-name=<name>] [--public-ip=<ip>] [--create-external-load-balancer]
 
-    // Creates a service for a replicated nginx, which serves on port 80 and connects to the containers on port 8000.
-    $ kubectl expose nginx --port=80 --container-port=8000
+### Examples
 
-    // Create a service for a replicated streaming application on port 4100 balancing UDP traffic and named 'video-stream'.
-    $ kubectl expose streamer --port=4100 --protocol=udp --service-name=video-stream
+```
+// Creates a service for a replicated nginx, which serves on port 80 and connects to the containers on port 8000.
+$ kubectl expose nginx --port=80 --container-port=8000
 
-kubectl expose <name> --port=<port> [--protocol=TCP|UDP] [--container-port=<number-or-name>] [--service-name=<name>] [--public-ip=<ip>] [--create-external-load-balancer]
+// Create a service for a replicated streaming application on port 4100 balancing UDP traffic and named 'video-stream'.
+$ kubectl expose streamer --port=4100 --protocol=udp --service-name=video-stream
+```
 
 ### Options
 

docs/kubectl-get.md

@@ -4,32 +4,36 @@ Display one or many resources
 
 ### Synopsis
 
+```
 Display one or many resources.
 
 Possible resources include pods (po), replication controllers (rc), services
 (se), minions (mi), or events (ev).
 
 By specifying the output as 'template' and providing a Go template as the value
 of the --template flag, you can filter the attributes of the fetched resource(s).
+```
 
-Examples:
+kubectl get [(-o|--output=)json|yaml|template|...] <resource> [<id>]
 
-    // List all pods in ps output format.
-    $ kubectl get pods
+### Examples
 
-    // List a single replication controller with specified ID in ps output format.
-    $ kubectl get replicationController 1234-56-7890-234234-456456
+```
+// List all pods in ps output format.
+$ kubectl get pods
 
-    // List a single pod in JSON output format.
-    $ kubectl get -o json pod 1234-56-7890-234234-456456
+// List a single replication controller with specified ID in ps output format.
+$ kubectl get replicationController 1234-56-7890-234234-456456
 
-    // Return only the status value of the specified pod.
-    $ kubectl get -o template pod 1234-56-7890-234234-456456 --template={{.currentState.status}}
+// List a single pod in JSON output format.
+$ kubectl get -o json pod 1234-56-7890-234234-456456
 
-    // List all replication controllers and services together in ps output format.
-    $ kubectl get rc,services
+// Return only the status value of the specified pod.
+$ kubectl get -o template pod 1234-56-7890-234234-456456 --template={{.currentState.status}}
 
-kubectl get [(-o|--output=)json|yaml|template|...] <resource> [<id>]
+// List all replication controllers and services together in ps output format.
+$ kubectl get rc,services
+```
 
 ### Options