Doc generation should remove old doc files

Right now, our doc generation scripts notice if you make changes and
don't regen docs, don't include new docs, etc.  But they miss it if your
changes should have REMOVED a doc.  Both kubectl-apiversion and
kubectl-clusterinfo should have been removed, but weren't.

This patch starts tracking all generated doc files and will cause
problems if files should be removed and aren't.

contrib/completions/bash/.files_generated

@@ -0,0 +1 @@
+kubectl

docs/.files_generated

@@ -0,0 +1,28 @@
+kubectl_api-versions.md
+kubectl_cluster-info.md
+kubectl_config.md
+kubectl_config_set-cluster.md
+kubectl_config_set-context.md
+kubectl_config_set-credentials.md
+kubectl_config_set.md
+kubectl_config_unset.md
+kubectl_config_use-context.md
+kubectl_config_view.md
+kubectl_create.md
+kubectl_delete.md
+kubectl_describe.md
+kubectl_exec.md
+kubectl_expose.md
+kubectl_get.md
+kubectl_label.md
+kubectl_log.md
+kubectl.md
+kubectl_namespace.md
+kubectl_port-forward.md
+kubectl_proxy.md
+kubectl_resize.md
+kubectl_rolling-update.md
+kubectl_run-container.md
+kubectl_stop.md
+kubectl_update.md
+kubectl_version.md

docs/man/man1/.files_generated

@@ -0,0 +1,28 @@
+kubectl.1
+kubectl-api-versions.1
+kubectl-cluster-info.1
+kubectl-config.1
+kubectl-config-set.1
+kubectl-config-set-cluster.1
+kubectl-config-set-context.1
+kubectl-config-set-credentials.1
+kubectl-config-unset.1
+kubectl-config-use-context.1
+kubectl-config-view.1
+kubectl-create.1
+kubectl-delete.1
+kubectl-describe.1
+kubectl-exec.1
+kubectl-expose.1
+kubectl-get.1
+kubectl-label.1
+kubectl-log.1
+kubectl-namespace.1
+kubectl-port-forward.1
+kubectl-proxy.1
+kubectl-resize.1
+kubectl-rolling-update.1
+kubectl-run-container.1
+kubectl-stop.1
+kubectl-update.1
+kubectl-version.1

hack/lib/util.sh

@@ -118,3 +118,31 @@ kube::util::wait-for-jobs() {
   done
   return ${fail}
 }
+
+# takes a binary to run $1 and then copies the results to $2
+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
+
+  # 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
+  local tmpdir="${KUBE_ROOT}/doc_tmp"
+  mkdir "${tmpdir}"
+  # generate the new files
+  ${cmd} "${tmpdir}"
+  # create the list of generated files
+  ls "${tmpdir}" | sort > "${tmpdir}/.files_generated"
+  # put the new generated file into the destination
+  find "${tmpdir}" -exec rsync -pt {} "${dest}" \; >/dev/null
+  #cleanup
+  rm -rf "${tmpdir}"
+}
+
+# ex: ts=2 sw=2 et filetype=sh

hack/run-gendocs.sh

@@ -45,6 +45,8 @@ if [[ ! -x "$gendocs" || ! -x "$genman" || ! -x "$genbashcomp" ]]; then
   exit 1
 fi
 
-${gendocs} "${KUBE_ROOT}/docs/"
-${genman} "${KUBE_ROOT}/docs/man/man1/"
-${genbashcomp} "${KUBE_ROOT}/contrib/completions/bash/"
+kube::util::gen-doc "${gendocs}" "${KUBE_ROOT}/docs/"
+kube::util::gen-doc "${genman}" "${KUBE_ROOT}/docs/man/man1"
+kube::util::gen-doc "${genbashcomp}" "${KUBE_ROOT}/contrib/completions/bash/"
+
+# ex: ts=2 sw=2 et filetype=sh

hack/verify-gendocs.sh

@@ -46,10 +46,13 @@ fi
 
 DOCROOT="${KUBE_ROOT}/docs/"
 TMP_DOCROOT="${KUBE_ROOT}/docs_tmp/"
+
 cp -a "${DOCROOT}" "${TMP_DOCROOT}"
-echo "diffing ${DOCROOT} against generated output from ${genman}"
-${genman} "${TMP_DOCROOT}/man/man1/"
-${gendocs} "${TMP_DOCROOT}"
+
+kube::util::gen-doc "${genman}" "${TMP_DOCROOT}/man/man1/"
+kube::util::gen-doc "${gendocs}" "${TMP_DOCROOT}"
+
+echo "diffing ${DOCROOT} against freshly generated docs"
 set +e
 diff -Naupr -I 'Auto generated by' "${DOCROOT}" "${TMP_DOCROOT}"
 ret=$?
@@ -57,16 +60,16 @@ set -e
 rm -rf "${TMP_DOCROOT}"
 if [ $ret -eq 0 ]
 then
-	echo "${DOCROOT} up to date."
+  echo "${DOCROOT} up to date."
 else
-	echo "${DOCROOT} is out of date. Please run hack/run-gendocs.sh"
-	exit 1
+  echo "${DOCROOT} is out of date. Please run hack/run-gendocs.sh"
+  exit 1
 fi
 
 COMPROOT="${KUBE_ROOT}/contrib/completions"
 TMP_COMPROOT="${KUBE_ROOT}/contrib/completions_tmp"
 cp -a "${COMPROOT}" "${TMP_COMPROOT}"
-${genbashcomp} "${TMP_COMPROOT}/bash/"
+kube::util::gen-doc "${genbashcomp}" "${TMP_COMPROOT}/bash/"
 set +e
 diff -Naupr "${COMPROOT}" "${TMP_COMPROOT}"
 ret=$?
@@ -79,3 +82,5 @@ else
 	echo "${COMPROOT} is out of date. Please run hack/run-gendocs.sh"
 	exit 1
 fi
+
+# ex: ts=2 sw=2 et filetype=sh