Merge pull request #5345 from jlowdermilk/kubectl-docs

Fix md generation for kubectl docs

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
-```
 
+Display addresses of the master and services with label kubernetes.io/cluster-service=true
+
+```
 kubectl clusterinfo
+```
 
 ### Options inherrited from parent commands
 

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]
 ```
 
-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
+
+// 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
 

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
 

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
+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
 

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.
 
-		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
 

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
 

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
+Sets the current-context in a .kubeconfig file
+
+```
+kubectl config use-context CONTEXT_NAME
+```
 
 ### Options inherrited from parent commands
 

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.
-```
 
+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

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>
+config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context"
+
+```
+kubectl config SUBCOMMAND
+```
 
 ### Options
 

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
 

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
 

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
 

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...>]
+Execute a command in a container.
+
+```
+kubectl exec -p POD -c CONTAINER -- COMMAND [args...]
+```
 
 ### Examples
 

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
 

docs/kubectl-get.md

@@ -4,7 +4,7 @@ Display one or many resources
 
 ### Synopsis
 
-```
+
 Display one or many resources.
 
 Possible resources include pods (po), replication controllers (rc), services
@@ -12,9 +12,10 @@ Possible resources include pods (po), replication controllers (rc), services
 
 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
 

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
 

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>]
+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]
+```
 
 ### Examples
 

docs/kubectl-namespace.md

@@ -4,14 +4,15 @@ SUPERCEDED: Set and view the current Kubernetes namespace
 
 ### Synopsis
 
-```
+
 SUPERCEDED:  Set and view the current Kubernetes namespace scope for command line requests.
 
 namespace has been superceded by the context.namespace field of .kubeconfig files.  See 'kubectl config set-context --help' for more details.
 
-```
 
-kubectl namespace [<namespace>]
+```
+kubectl namespace [namespace]
+```
 
 ### Options inherrited from parent commands
 

docs/kubectl-port-forward.md

@@ -4,26 +4,28 @@ Forward 1 or more local ports to a pod.
 
 ### Synopsis
 
-```
-Forward 1 or more local ports to a pod.
-```
 
-kubectl port-forward -p <pod> [<local port>:]<remote port> [<port>...]
+Forward 1 or more local ports to a pod.
+
+```
+kubectl port-forward -p POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]
+```
 
 ### Examples
 
 ```
+
+// listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod
 $ kubectl port-forward -p mypod 5000 6000
-<listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod>
 
+// listens on port 8888 locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod 8888:5000
-<listens on port 8888 locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod :5000
-<listens on a random port locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod 0:5000
-<listens on a random port locally, forwarding to 5000 in the pod> 
 ```
 
 ### Options

docs/kubectl-proxy.md

@@ -4,11 +4,23 @@ Run a proxy to the Kubernetes API server
 
 ### Synopsis
 
+
+Run a proxy to the Kubernetes API server. 
+
 ```
-Run a proxy to the Kubernetes API server.
+kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix]
 ```
 
-kubectl proxy
+### Examples
+
+```
+// Run a proxy to kubernetes apiserver on port 8011, serving static content from ./local/www/
+$ kubectl proxy --port=8011 --www=./local/www/
+
+// Run a proxy to kubernetes apiserver, changing the api prefix to k8s-api
+// This makes e.g. the pods api available at localhost:8011/k8s-api/v1beta1/pods/
+$ kubectl proxy --api-prefix=k8s-api
+```
 
 ### Options
 

docs/kubectl-resize.md

@@ -4,16 +4,17 @@ Set a new size for a Replication Controller.
 
 ### Synopsis
 
-```
+
 Set a new size for a Replication Controller.
 
 Resize also allows users to specify one or more preconditions for the resize action.
 If --current-replicas or --resource-version is specified, it is validated before the
 resize is attempted, and it is guaranteed that the precondition holds true when the
 resize is sent to the server.
-```
 
-kubectl resize [--resource-version=<version>] [--current-replicas=<count>] --replicas=<count> <resource> <id>
+```
+kubectl resize [--resource-version=version] [--current-replicas=count] --replicas=COUNT RESOURCE ID
+```
 
 ### Examples
 

docs/kubectl-rollingupdate.md

@@ -4,15 +4,16 @@ Perform a rolling update of the given ReplicationController.
 
 ### Synopsis
 
-```
+
 Perform a rolling update of the given ReplicationController.
 
 Replaces the specified controller with new controller, updating one pod at a time to use the
 new PodTemplate. The new-controller.json must specify the same namespace as the
 existing controller and overwrite at least one (common) label in its replicaSelector.
-```
 
-kubectl rollingupdate <old-controller-name> -f <new-controller.json>
+```
+kubectl rollingupdate OLD_CONTROLLER_NAME -f NEW_CONTROLLER_SPEC
+```
 
 ### Examples
 

docs/kubectl-run-container.md

@@ -4,12 +4,13 @@ Run a particular image on the cluster.
 
 ### Synopsis
 
-```
+
 Create and run a particular image, possibly replicated.
 Creates a replication controller to manage the created container(s).
-```
 
-kubectl run-container <name> --image=<image> [--port=<port>] [--replicas=replicas] [--dry-run=<bool>] [--overrides=<inline-json>]
+```
+kubectl run-container NAME --image=image [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json]
+```
 
 ### Examples
 

docs/kubectl-stop.md

@@ -4,14 +4,15 @@ Gracefully shut down a resource by id or filename.
 
 ### Synopsis
 
-```
+
 Gracefully shut down a resource by id or filename.
 
 Attempts to shut down and delete a resource that supports graceful termination.
 If the resource is resizable it will be resized to 0 before deletion.
-```
 
-kubectl stop (-f filename | <resource> (<id> | -l <label> | --all))
+```
+kubectl stop (-f FILENAME | RESOURCE (ID | -l label | --all))
+```
 
 ### Examples
 

docs/kubectl-update.md

@@ -4,13 +4,14 @@ Update a resource by filename or stdin.
 
 ### Synopsis
 
-```
+
 Update a resource by filename or stdin.
 
 JSON and YAML formats are accepted.
-```
 
-kubectl update -f filename
+```
+kubectl update -f FILENAME
+```
 
 ### Examples
 

docs/kubectl-version.md

@@ -4,11 +4,12 @@ Print the client and server version information.
 
 ### Synopsis
 
-```
-Print the client and server version information.
-```
 
+Print the client and server version information.
+
+```
 kubectl version
+```
 
 ### Options
 

docs/kubectl.md

@@ -4,13 +4,14 @@ kubectl controls the Kubernetes cluster manager
 
 ### Synopsis
 
-```
+
 kubectl controls the Kubernetes cluster manager.
 
 Find more information at https://github.com/GoogleCloudPlatform/kubernetes.
-```
 
+```
 kubectl
+```
 
 ### Options
 

docs/man/man1/kubectl-config-set-cluster.1

@@ -13,11 +13,8 @@ kubectl config set\-cluster \- Sets a cluster entry in .kubeconfig
 
 .SH DESCRIPTION
 .PP
-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.
+Sets a cluster entry in .kubeconfig.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
 
 
 .SH OPTIONS
@@ -144,6 +141,24 @@ Sets a cluster entry in .kubeconfig
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// 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
+
+// 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
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,

docs/man/man1/kubectl-config-set-context.1

@@ -14,10 +14,7 @@ kubectl config set\-context \- Sets a context entry in .kubeconfig
 .SH DESCRIPTION
 .PP
 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.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
@@ -138,6 +135,18 @@ Sets a context entry in .kubeconfig
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// Set the user field on the gce context entry without touching other values
+$ kubectl config set\-context gce \-\-user=cluster\-admin
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,

docs/man/man1/kubectl-config-set-credentials.1

@@ -14,20 +14,7 @@ kubectl config set\-credentials \- Sets a user entry in .kubeconfig
 .SH DESCRIPTION
 .PP
 Sets a user entry in .kubeconfig
-
-.PP
-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:
-
-.PP
-.RS
-
-.nf
-set\-credentials cluster\-admin \-\-client\-key=\~/.kube/admin.key
-
-.fi
-.RE
+Specifying a name that already exists will merge new fields on top of existing values.
 
 .PP
 Client\-certificate flags:
@@ -169,6 +156,25 @@ Bearer token and basic auth are mutually exclusive.
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// 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
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,

docs/man/man1/kubectl-config-set.1

@@ -14,16 +14,8 @@ kubectl config set \- Sets an individual value in a .kubeconfig file
 .SH DESCRIPTION
 .PP
 Sets an individual value in a .kubeconfig file
-
-.PP
-.RS
-
-.nf
-    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.
-
-.fi
-.RE
+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.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS

docs/man/man1/kubectl-config-unset.1

@@ -14,15 +14,7 @@ kubectl config unset \- Unsets an individual value in a .kubeconfig file
 .SH DESCRIPTION
 .PP
 Unsets an individual value in a .kubeconfig file
-
-.PP
-.RS
-
-.nf
-    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.
-
-.fi
-.RE
+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.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS

docs/man/man1/kubectl-config-view.1

@@ -15,6 +15,9 @@ kubectl config view \- displays merged .kubeconfig settings or a specified .kube
 .PP
 displays merged .kubeconfig settings or a specified .kubeconfig file.
 
+.PP
+You can use \-\-output=template \-\-template=TEMPLATE to extract specific values.
+
 
 .SH OPTIONS
 .PP
@@ -168,6 +171,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" \}\}'
+
 .fi
 .RE
 

docs/man/man1/kubectl-port-forward.1

@@ -133,17 +133,18 @@ Forward 1 or more local ports to a pod.
 .RS
 
 .nf
+
+// listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod
 $ kubectl port\-forward \-p mypod 5000 6000
-<listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod>
 
+// listens on port 8888 locally, forwarding to 5000 in the pod
 $ kubectl port\-forward \-p mypod 8888:5000
-<listens on port 8888 locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port\-forward \-p mypod :5000
-<listens on a random port locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port\-forward \-p mypod 0:5000
-<listens on a random port locally, forwarding to 5000 in the pod> 
 
 .fi
 .RE

docs/man/man1/kubectl-proxy.1

@@ -140,6 +140,22 @@ Run a proxy to the Kubernetes API server.
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// Run a proxy to kubernetes apiserver on port 8011, serving static content from ./local/www/
+$ kubectl proxy \-\-port=8011 \-\-www=./local/www/
+
+// Run a proxy to kubernetes apiserver, changing the api prefix to k8s\-api
+// This makes e.g. the pods api available at localhost:8011/k8s\-api/v1beta1/pods/
+$ kubectl proxy \-\-api\-prefix=k8s\-api
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl(1)\fP,