Merge pull request #6765 from eparis/track-deleted-generated-docs

Doc generation should remove old doc files

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=$?
@@ -66,7 +69,7 @@ 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