Fix md generation for kubectl docs

Display usage string, not long help, as code, remove angle brackets from output (.md interprets as tags and hides).
duda · Mar 11, 2015 · a5746c9 · a5746c9
1 parent 7d53425
commit a5746c9
Show file tree

Hide file tree

Showing 60 changed files with 370 additions and 232 deletions.
diff --git a/cmd/gendocs/gen_kubectl_docs.go b/cmd/gendocs/gen_kubectl_docs.go
@@ -65,10 +65,10 @@ 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, "```\n%s\n```\n\n", long)
+	fmt.Fprintf(out, "\n%s\n\n", long)
 
 	if command.Runnable() {
-		fmt.Fprintf(out, "%s\n\n", command.UseLine())
+		fmt.Fprintf(out, "```\n%s\n```\n\n", command.UseLine())
 	}
 
 	if len(command.Example) > 0 {

diff --git a/docs/kubectl-clusterinfo.md b/docs/kubectl-clusterinfo.md
@@ -4,11 +4,12 @@ Display cluster info
 
 ### Synopsis
 
-```
+
 Display addresses of the master and services with label kubernetes.io/cluster-service=true
-```
 
+```
 kubectl clusterinfo
+```
 
 ### Options inherrited from parent commands
 

diff --git a/docs/kubectl-config-set-cluster.md b/docs/kubectl-config-set-cluster.md
@@ -4,16 +4,26 @@ 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.
+
 ```
-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]
+```
+
+### Examples
+
 ```
+// Set only the server field on the e2e cluster entry without touching other values.
+$ kubectl config set-cluster e2e --server=https://1.2.3.4
 
-kubectl config set-cluster name [--server=server] [--certificate-authority=path/to/certficate/authority] [--api-version=apiversion] [--insecure-skip-tls-verify=true]
+// Embed certificate authority data for the e2e cluster entry
+$ kubectl config set-cluster e2e --certificate-authority=~/.kube/e2e/kubernetes.ca.crt
+
+// Disable cert checking for the dev cluster entry
+$ kubectl config set-cluster e2e --insecure-skip-tls-verify=true
+```
 
 ### Options
 

diff --git a/docs/kubectl-config-set-context.md b/docs/kubectl-config-set-context.md
@@ -4,15 +4,20 @@ 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.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
+
+```
+kubectl config set-context NAME [--cluster=cluster_nickname] [--user=user_nickname] [--namespace=namespace]
 ```
 
-kubectl config set-context name [--cluster=cluster-nickname] [--user=user-nickname] [--namespace=namespace]
+### Examples
+
+```
+// Set the user field on the gce context entry without touching other values
+$ kubectl config set-context gce --user=cluster-admin
+```
 
 ### Options inherrited from parent commands
 

diff --git a/docs/kubectl-config-set-credentials.md b/docs/kubectl-config-set-credentials.md
@@ -4,14 +4,9 @@ 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 example, the following only sets the "client-key" field on the 
-  "cluster-admin" entry, without touching other values:
 
-    set-credentials cluster-admin --client-key=~/.kube/admin.key
+Sets a user entry in .kubeconfig
+Specifying a name that already exists will merge new fields on top of existing values.
 
   Client-certificate flags:
     --client-certificate=certfile --client-key=keyfile
@@ -24,9 +19,24 @@ Sets a user entry in .kubeconfig
 
   Bearer token and basic auth are mutually exclusive.
 
+
+```
+kubectl config set-credentials NAME [--auth-path=/path/to/authfile] [--client-certificate=path/to/certfile] [--client-key=path/to/keyfile] [--token=bearer_token] [--username=basic_user] [--password=basic_password]
 ```
 
-kubectl config set-credentials name [--auth-path=authfile] [--client-certificate=certfile] [--client-key=keyfile] [--token=bearer_token] [--username=basic_user] [--password=basic_password]
+### Examples
+
+```
+// Set only the "client-key" field on the "cluster-admin"
+// entry, without touching other values:
+$ kubectl set-credentials cluster-admin --client-key=~/.kube/admin.key
+
+// Set basic auth for the "cluster-admin" entry
+$ kubectl set-credentials cluster-admin --username=admin --password=uXFGweU9l35qcif
+
+// Embed client certificate data in the "cluster-admin" entry
+$ kubectl set-credentials cluster-admin --client-certificate=~/.kube/admin.crt --embed-certs=true
+```
 
 ### Options
 

diff --git a/docs/kubectl-config-set.md b/docs/kubectl-config-set.md
@@ -4,16 +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.
+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
+kubectl config set PROPERTY_NAME PROPERTY_VALUE
+```
 
 ### Options inherrited from parent commands
 

diff --git a/docs/kubectl-config-unset.md b/docs/kubectl-config-unset.md
@@ -4,14 +4,13 @@ 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.
 
-		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
+kubectl config unset PROPERTY_NAME
+```
 
 ### Options inherrited from parent commands
 

diff --git a/docs/kubectl-config-use-context.md b/docs/kubectl-config-use-context.md
@@ -4,11 +4,12 @@ Sets the current-context in a .kubeconfig file
 
 ### Synopsis
 
-```
+
 Sets the current-context in a .kubeconfig file
-```
 
-kubectl config use-context context-name
+```
+kubectl config use-context CONTEXT_NAME
+```
 
 ### Options inherrited from parent commands
 

diff --git a/docs/kubectl-config-view.md b/docs/kubectl-config-view.md
@@ -4,11 +4,14 @@ displays merged .kubeconfig settings or a specified .kubeconfig file.
 
 ### Synopsis
 
-```
+
 displays merged .kubeconfig settings or a specified .kubeconfig file.
-```
 
+You can use --output=template --template=TEMPLATE to extract specific values.
+
+```
 kubectl config view
+```
 
 ### Examples
 
@@ -18,6 +21,9 @@ $ kubectl config view
 
 // Show only local ./.kubeconfig settings
 $ kubectl config view --local
+
+// Get the password for the e2e user
+$ kubectl config view -o template --template='{{ index . "users" "e2e" "password" }}'
 ```
 
 ### Options

diff --git a/docs/kubectl-config.md b/docs/kubectl-config.md
@@ -4,11 +4,12 @@ config modifies .kubeconfig files
 
 ### Synopsis
 
-```
+
 config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context"
-```
 
-kubectl config <subcommand>
+```
+kubectl config SUBCOMMAND
+```
 
 ### Options
 

diff --git a/docs/kubectl-create.md b/docs/kubectl-create.md
@@ -4,13 +4,14 @@ Create a resource by filename or stdin
 
 ### Synopsis
 
-```
+
 Create a resource by filename or stdin.
 
 JSON and YAML formats are accepted.
-```
 
-kubectl create -f filename
+```
+kubectl create -f FILENAME
+```
 
 ### Examples
 

diff --git a/docs/kubectl-delete.md b/docs/kubectl-delete.md
@@ -4,7 +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.
@@ -15,9 +15,10 @@ 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.
-```
 
-kubectl delete (-f filename | <resource> (<id> | -l <label> | --all))
+```
+kubectl delete ([-f FILENAME] | (RESOURCE [(ID | -l label | --all)]
+```
 
 ### Examples
 

diff --git a/docs/kubectl-describe.md b/docs/kubectl-describe.md
@@ -4,14 +4,15 @@ 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>
+```
+kubectl describe RESOURCE ID
+```
 
 ### Options inherrited from parent commands
 

diff --git a/docs/kubectl-exec.md b/docs/kubectl-exec.md
@@ -4,11 +4,12 @@ Execute a command in a container.
 
 ### Synopsis
 
-```
+
 Execute a command in a container.
-```
 
-kubectl exec -p <pod> -c <container> -- <command> [<args...>]
+```
+kubectl exec -p POD -c CONTAINER -- COMMAND [args...]
+```
 
 ### Examples
 

diff --git a/docs/kubectl-expose.md b/docs/kubectl-expose.md
@@ -4,14 +4,15 @@ 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.
-```
 
-kubectl expose <name> --port=<port> [--protocol=TCP|UDP] [--container-port=<number-or-name>] [--service-name=<name>] [--public-ip=<ip>] [--create-external-load-balancer]
+```
+kubectl expose NAME --port=port [--protocol=TCP|UDP] [--container-port=number-or-name] [--service-name=name] [--public-ip=ip] [--create-external-load-balancer=bool]
+```
 
 ### Examples
 

diff --git a/docs/kubectl-get.md b/docs/kubectl-get.md
@@ -4,17 +4,18 @@ 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).
-```
 
-kubectl get [(-o|--output=)json|yaml|template|...] <resource> [<id>]
+```
+kubectl get [(-o|--output=)json|yaml|template|...] RESOURCE [ID]
+```
 
 ### Examples
 

diff --git a/docs/kubectl-label.md b/docs/kubectl-label.md
@@ -4,14 +4,15 @@ Update the labels on a resource
 
 ### Synopsis
 
-```
+
 Update the labels on a resource.
 
 If --overwrite is true, then existing labels can be overwritten, otherwise attempting to overwrite a label will result in an error.
 If --resource-version is specified, then updates will use this resource version, otherwise the existing resource-version will be used.
-```
 
-kubectl label [--overwrite] <resource> <name> <key-1>=<val-1> ... <key-n>=<val-n> [--resource-version=<version>]
+```
+kubectl label [--overwrite] RESOURCE NAME KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]
+```
 
 ### Examples
 

diff --git a/docs/kubectl-log.md b/docs/kubectl-log.md
@@ -4,11 +4,12 @@ Print the logs for a container in a pod.
 
 ### Synopsis
 
-```
+
 Print the logs for a container in a pod. If the pod has only one container, the container name is optional.
-```
 
-kubectl log [-f] <pod> [<container>]
+```
+kubectl log [-f] POD [CONTAINER]
+```
 
 ### Examples