Merge pull request #7228 from jlowdermilk/describe-examples

Add examples for kubectl describe, make gendocs less spammy

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")