Add examples for kubectl describe, and make gendocs less spammy

docs/kubectl_describe.md

@@ -11,7 +11,17 @@ This command joins many API calls together to form a detailed description of a
 given resource.
 
 ```
-kubectl describe RESOURCE ID
+kubectl describe (RESOURCE NAME | RESOURCE/NAME)
+```
+
+### Examples
+
+```
+// Describe a node
+$ kubectl describe nodes kubernetes-minion-emt8.c.myproject.internal
+
+// Describe a pod
+$ kubectl describe pods/nginx
 ```
 
 ### Options
@@ -53,4 +63,4 @@ kubectl describe RESOURCE ID
 ### SEE ALSO
 * [kubectl](kubectl.md)	 - kubectl controls the Kubernetes cluster manager
 
-###### Auto generated by spf13/cobra at 2015-04-23 00:47:55.40003297 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-04-23 21:21:05.485819349 +0000 UTC

docs/man/man1/kubectl-describe.1

@@ -128,6 +128,21 @@ given resource.
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// Describe a node
+$ kubectl describe nodes kubernetes\-minion\-emt8.c.myproject.internal
+
+// Describe a pod
+$ kubectl describe pods/nginx
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl(1)\fP,

hack/lib/util.sh

@@ -119,17 +119,13 @@ kube::util::wait-for-jobs() {
   return ${fail}
 }
 
-# takes a binary to run $1 and then copies the results to $2
+# Takes a binary to run $1 and then copies the results to $2.
+# If the generated and original files are the same after filtering lines
+# that match $3, copy is skipped.
 kube::util::gen-doc() {
   local cmd="$1"
   local dest="$2"
-
-  # remove all old generated file from the destination
-  for file in $(cat "${dest}/.files_generated" 2>/dev/null); do
-    set +e
-    rm "${dest}/${file}"
-    set -e
-  done
+  local skipprefix="${3:-}"
 
   # We do this in a tmpdir in case the dest has other non-autogenned files
   # We don't want to include them in the list of gen'd files
@@ -139,6 +135,22 @@ kube::util::gen-doc() {
   ${cmd} "${tmpdir}"
   # create the list of generated files
   ls "${tmpdir}" | LC_ALL=C sort > "${tmpdir}/.files_generated"
+
+  # remove all old generated file from the destination
+  while read file; do
+    if [[ -e "${tmpdir}/${file}" && -n "${skipprefix}" ]]; then
+      local original generated
+      original=$(grep -v "^${skipprefix}" "${dest}/${file}") || :
+      generated=$(grep -v "^${skipprefix}" "${tmpdir}/${file}") || :
+      if [[ "${original}" == "${generated}" ]]; then
+        # overwrite generated with original.
+        mv "${dest}/${file}" "${tmpdir}/${file}"
+      fi
+    else
+      rm "${dest}/${file}" || true
+    fi
+  done <"${dest}/.files_generated"
+
   # put the new generated file into the destination
   find "${tmpdir}" -exec rsync -pt {} "${dest}" \; >/dev/null
   #cleanup

hack/run-gendocs.sh

@@ -24,12 +24,6 @@ source "${KUBE_ROOT}/hack/lib/init.sh"
 kube::golang::setup_env
 "${KUBE_ROOT}/hack/build-go.sh" cmd/gendocs cmd/genman cmd/genbashcomp
 
-# Get the absolute path of the directory component of a file, i.e. the
-# absolute path of the dirname of $1.
-get_absolute_dirname() {
-  echo "$(cd "$(dirname "$1")" && pwd)"
-}
-
 # Find binary
 gendocs=$(kube::util::find-binary "gendocs")
 genman=$(kube::util::find-binary "genman")
@@ -45,7 +39,7 @@ if [[ ! -x "$gendocs" || ! -x "$genman" || ! -x "$genbashcomp" ]]; then
   exit 1
 fi
 
-kube::util::gen-doc "${gendocs}" "${KUBE_ROOT}/docs/"
+kube::util::gen-doc "${gendocs}" "${KUBE_ROOT}/docs/" '###### Auto generated by spf13/cobra'
 kube::util::gen-doc "${genman}" "${KUBE_ROOT}/docs/man/man1"
 kube::util::gen-doc "${genbashcomp}" "${KUBE_ROOT}/contrib/completions/bash/"
 

hack/verify-gendocs.sh

@@ -24,12 +24,6 @@ source "${KUBE_ROOT}/hack/lib/init.sh"
 kube::golang::setup_env
 "${KUBE_ROOT}/hack/build-go.sh" cmd/gendocs cmd/genman cmd/genbashcomp
 
-# Get the absolute path of the directory component of a file, i.e. the
-# absolute path of the dirname of $1.
-get_absolute_dirname() {
-  echo "$(cd "$(dirname "$1")" && pwd)"
-}
-
 gendocs=$(kube::util::find-binary "gendocs")
 genman=$(kube::util::find-binary "genman")
 genbashcomp=$(kube::util::find-binary "genbashcomp")

pkg/kubectl/cmd/describe.go

@@ -29,12 +29,17 @@ import (
 
 func NewCmdDescribe(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "describe RESOURCE ID",
+		Use:   "describe (RESOURCE NAME | RESOURCE/NAME)",
 		Short: "Show details of a specific resource",
 		Long: `Show details of a specific resource.
 
 This command joins many API calls together to form a detailed description of a
 given resource.`,
+		Example: `// Describe a node
+$ kubectl describe nodes kubernetes-minion-emt8.c.myproject.internal
+
+// Describe a pod
+$ kubectl describe pods/nginx`,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunDescribe(f, out, cmd, args)
 			cmdutil.CheckErr(err)