From 9cf7bb6b4fba30326add42768f4e6d41e343c714 Mon Sep 17 00:00:00 2001 From: Eric Paris Date: Thu, 20 Aug 2015 18:28:05 -0700 Subject: [PATCH 1/2] Automatically clean up KUBE_TEMP kube::util:ensure-temp-dir claims that it will automatically clean it up. But it obviously doesn't. Since we cannot add multiple trap in bash add a function that lets us trap and clean up KUBE_TEMP even if someone already set a trap. --- hack/lib/util.sh | 31 +++++++++++++++++++++++++++++++ hack/test-cmd.sh | 3 +-- 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/hack/lib/util.sh b/hack/lib/util.sh index 82ad2354a72..029ca02edf2 100755 --- a/hack/lib/util.sh +++ b/hack/lib/util.sh @@ -48,6 +48,36 @@ kube::util::wait_for_url() { return 1 } +# Example: kube::util::trap_add 'echo "in trap DEBUG"' DEBUG +# See: http://stackoverflow.com/questions/3338030/multiple-bash-traps-for-the-same-signal +kube::util::trap_add() { + local trap_add_cmd + trap_add_cmd=$1 + shift + + for trap_add_name in "$@"; do + local existing_cmd + local new_cmd + + # Grab the currently defined trap commands for this trap + existing_cmd=`trap -p "${trap_add_name}" | awk -F"'" '{print $2}'` + + if [[ -z "${existing_cmd}" ]]; then + new_cmd="${trap_add_cmd}" + else + new_cmd="${existing_cmd};${trap_add_cmd}" + fi + + # Assign the test + trap "${new_cmd}" "${trap_add_name}" + done +} + +# Opposite of kube::util::ensure-temp-dir() +kube::util::cleanup-temp-dir() { + rm -rf "${KUBE_TEMP}" +} + # Create a temp dir that'll be deleted at the end of this bash session. # # Vars set: @@ -55,6 +85,7 @@ kube::util::wait_for_url() { kube::util::ensure-temp-dir() { if [[ -z ${KUBE_TEMP-} ]]; then KUBE_TEMP=$(mktemp -d 2>/dev/null || mktemp -d -t kubernetes.XXXXXX) + kube::util::trap_add kube::util::cleanup-temp-dir EXIT fi } diff --git a/hack/test-cmd.sh b/hack/test-cmd.sh index 2ffa525c381..a17865dba15 100755 --- a/hack/test-cmd.sh +++ b/hack/test-cmd.sh @@ -74,8 +74,7 @@ function check-curl-proxy-code() echo "For address ${full_address}, got ${status} but wanted ${desired}" return 1 } - -trap cleanup EXIT SIGINT +kube::util::trap_add cleanup EXIT SIGINT kube::util::ensure-temp-dir kube::etcd::start From 58d6b29e972b9d0ce4314e3444eed5bfb9a393c7 Mon Sep 17 00:00:00 2001 From: Eric Paris Date: Thu, 20 Aug 2015 19:17:26 -0700 Subject: [PATCH 2/2] Rework doc generation to simplify and centralize Just do all doc generation in the hack::util::gen-docs instead of spread around. We also only track the generated docs in a single file for the whole tree. --- .generated_docs | 64 +++++++++++++++++++ contrib/completions/bash/.files_generated | 1 - docs/man/man1/.files_generated | 31 ---------- docs/user-guide/kubectl/.files_generated | 31 ---------- hack/after-build/update-generated-docs.sh | 22 ++++--- hack/after-build/verify-generated-docs.sh | 39 +++--------- hack/lib/util.sh | 75 ++++++++++------------- 7 files changed, 120 insertions(+), 143 deletions(-) create mode 100644 .generated_docs delete mode 100644 contrib/completions/bash/.files_generated delete mode 100644 docs/man/man1/.files_generated delete mode 100644 docs/user-guide/kubectl/.files_generated diff --git a/.generated_docs b/.generated_docs new file mode 100644 index 00000000000..fba53f0a03e --- /dev/null +++ b/.generated_docs @@ -0,0 +1,64 @@ +.generated_docs +contrib/completions/bash/kubectl +docs/man/man1/kubectl-annotate.1 +docs/man/man1/kubectl-api-versions.1 +docs/man/man1/kubectl-attach.1 +docs/man/man1/kubectl-cluster-info.1 +docs/man/man1/kubectl-config-set-cluster.1 +docs/man/man1/kubectl-config-set-context.1 +docs/man/man1/kubectl-config-set-credentials.1 +docs/man/man1/kubectl-config-set.1 +docs/man/man1/kubectl-config-unset.1 +docs/man/man1/kubectl-config-use-context.1 +docs/man/man1/kubectl-config-view.1 +docs/man/man1/kubectl-config.1 +docs/man/man1/kubectl-create.1 +docs/man/man1/kubectl-delete.1 +docs/man/man1/kubectl-describe.1 +docs/man/man1/kubectl-exec.1 +docs/man/man1/kubectl-expose.1 +docs/man/man1/kubectl-get.1 +docs/man/man1/kubectl-label.1 +docs/man/man1/kubectl-logs.1 +docs/man/man1/kubectl-namespace.1 +docs/man/man1/kubectl-patch.1 +docs/man/man1/kubectl-port-forward.1 +docs/man/man1/kubectl-proxy.1 +docs/man/man1/kubectl-replace.1 +docs/man/man1/kubectl-rolling-update.1 +docs/man/man1/kubectl-run.1 +docs/man/man1/kubectl-scale.1 +docs/man/man1/kubectl-stop.1 +docs/man/man1/kubectl-version.1 +docs/man/man1/kubectl.1 +docs/user-guide/kubectl/kubectl.md +docs/user-guide/kubectl/kubectl_annotate.md +docs/user-guide/kubectl/kubectl_api-versions.md +docs/user-guide/kubectl/kubectl_attach.md +docs/user-guide/kubectl/kubectl_cluster-info.md +docs/user-guide/kubectl/kubectl_config.md +docs/user-guide/kubectl/kubectl_config_set-cluster.md +docs/user-guide/kubectl/kubectl_config_set-context.md +docs/user-guide/kubectl/kubectl_config_set-credentials.md +docs/user-guide/kubectl/kubectl_config_set.md +docs/user-guide/kubectl/kubectl_config_unset.md +docs/user-guide/kubectl/kubectl_config_use-context.md +docs/user-guide/kubectl/kubectl_config_view.md +docs/user-guide/kubectl/kubectl_create.md +docs/user-guide/kubectl/kubectl_delete.md +docs/user-guide/kubectl/kubectl_describe.md +docs/user-guide/kubectl/kubectl_exec.md +docs/user-guide/kubectl/kubectl_expose.md +docs/user-guide/kubectl/kubectl_get.md +docs/user-guide/kubectl/kubectl_label.md +docs/user-guide/kubectl/kubectl_logs.md +docs/user-guide/kubectl/kubectl_namespace.md +docs/user-guide/kubectl/kubectl_patch.md +docs/user-guide/kubectl/kubectl_port-forward.md +docs/user-guide/kubectl/kubectl_proxy.md +docs/user-guide/kubectl/kubectl_replace.md +docs/user-guide/kubectl/kubectl_rolling-update.md +docs/user-guide/kubectl/kubectl_run.md +docs/user-guide/kubectl/kubectl_scale.md +docs/user-guide/kubectl/kubectl_stop.md +docs/user-guide/kubectl/kubectl_version.md diff --git a/contrib/completions/bash/.files_generated b/contrib/completions/bash/.files_generated deleted file mode 100644 index 4eb4f5f7b24..00000000000 --- a/contrib/completions/bash/.files_generated +++ /dev/null @@ -1 +0,0 @@ -kubectl diff --git a/docs/man/man1/.files_generated b/docs/man/man1/.files_generated deleted file mode 100644 index 01dd18c9c15..00000000000 --- a/docs/man/man1/.files_generated +++ /dev/null @@ -1,31 +0,0 @@ -kubectl-annotate.1 -kubectl-api-versions.1 -kubectl-attach.1 -kubectl-cluster-info.1 -kubectl-config-set-cluster.1 -kubectl-config-set-context.1 -kubectl-config-set-credentials.1 -kubectl-config-set.1 -kubectl-config-unset.1 -kubectl-config-use-context.1 -kubectl-config-view.1 -kubectl-config.1 -kubectl-create.1 -kubectl-delete.1 -kubectl-describe.1 -kubectl-exec.1 -kubectl-expose.1 -kubectl-get.1 -kubectl-label.1 -kubectl-logs.1 -kubectl-namespace.1 -kubectl-patch.1 -kubectl-port-forward.1 -kubectl-proxy.1 -kubectl-replace.1 -kubectl-rolling-update.1 -kubectl-run.1 -kubectl-scale.1 -kubectl-stop.1 -kubectl-version.1 -kubectl.1 diff --git a/docs/user-guide/kubectl/.files_generated b/docs/user-guide/kubectl/.files_generated deleted file mode 100644 index 815195aca62..00000000000 --- a/docs/user-guide/kubectl/.files_generated +++ /dev/null @@ -1,31 +0,0 @@ -kubectl.md -kubectl_annotate.md -kubectl_api-versions.md -kubectl_attach.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_logs.md -kubectl_namespace.md -kubectl_patch.md -kubectl_port-forward.md -kubectl_proxy.md -kubectl_replace.md -kubectl_rolling-update.md -kubectl_run.md -kubectl_scale.md -kubectl_stop.md -kubectl_version.md diff --git a/hack/after-build/update-generated-docs.sh b/hack/after-build/update-generated-docs.sh index 7f11ff63b0b..75c9894d13c 100755 --- a/hack/after-build/update-generated-docs.sh +++ b/hack/after-build/update-generated-docs.sh @@ -23,17 +23,23 @@ source "${KUBE_ROOT}/hack/lib/init.sh" kube::golang::setup_env -# Find binary -gendocs=$(kube::util::find-binary "gendocs") -genman=$(kube::util::find-binary "genman") -genbashcomp=$(kube::util::find-binary "genbashcomp") -mungedocs=$(kube::util::find-binary "mungedocs") +kube::util::ensure-temp-dir + +kube::util::gen-docs "${KUBE_TEMP}" + +# remove all of the old docs +while read file; do + rm "${KUBE_ROOT}/${file}" 2>/dev/null || true +done <"${KUBE_ROOT}/.generated_docs" + +# the shopt is so that we get .generated_docs from the glob. +shopt -s dotglob +cp -af "${KUBE_TEMP}"/* "${KUBE_ROOT}" +shopt -u dotglob -kube::util::gen-doc "${gendocs}" "${KUBE_ROOT}" "docs/user-guide/kubectl/" '###### 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/" kube::util::gen-analytics "${KUBE_ROOT}" +mungedocs=$(kube::util::find-binary "mungedocs") "${mungedocs}" "--root-dir=${KUBE_ROOT}/docs/" && ret=0 || ret=$? if [[ $ret -eq 1 ]]; then echo "${KUBE_ROOT}/docs/ requires manual changes. See preceding errors." diff --git a/hack/after-build/verify-generated-docs.sh b/hack/after-build/verify-generated-docs.sh index 04a6d4e36c6..52da068b7ec 100755 --- a/hack/after-build/verify-generated-docs.sh +++ b/hack/after-build/verify-generated-docs.sh @@ -31,11 +31,6 @@ mungedocs=$(kube::util::find-binary "mungedocs") DOCROOT="${KUBE_ROOT}/docs/" EXAMPLEROOT="${KUBE_ROOT}/examples/" -TMP_DOCROOT="${KUBE_ROOT}/_tmp/docs/" -_tmp="${KUBE_ROOT}/_tmp" - -mkdir -p "${_tmp}" -cp -a "${DOCROOT}" "${TMP_DOCROOT}" # mungedocs --verify can (and should) be run on the real docs, otherwise their # links will be distorted. --verify means that it will not make changes. @@ -59,12 +54,15 @@ if [[ $ret -gt 1 ]]; then exit 1 fi -kube::util::gen-doc "${genman}" "${_tmp}" "docs/man/man1/" -kube::util::gen-doc "${gendocs}" "${_tmp}" "docs/user-guide/kubectl/" '###### Auto generated by spf13/cobra' -echo "diffing ${DOCROOT} against freshly generated docs" -diff -Naupr "${DOCROOT}" "${TMP_DOCROOT}" && ret=0 || ret=$? -rm -rf "${_tmp}" +kube::util::ensure-temp-dir + +kube::util::gen-docs "${KUBE_TEMP}" +diff -Naup "${KUBE_TEMP}/.generated_docs" "${KUBE_ROOT}/.generated_docs" || ret=1 || true +while read file; do + diff -Naup "${KUBE_TEMP}/${file}" "${KUBE_ROOT}/${file}" || ret=1 || true +done <"${KUBE_TEMP}/.generated_docs" + needsanalytics=($(kube::util::gen-analytics "${KUBE_ROOT}" 1)) if [[ ${#needsanalytics[@]} -ne 0 ]]; then echo -e "Some md files are missing ga-beacon analytics link:" @@ -73,26 +71,9 @@ if [[ ${#needsanalytics[@]} -ne 0 ]]; then fi if [[ $ret -eq 0 ]] then - echo "${DOCROOT} up to date." + echo "Generated docs are up to date." else - echo "${DOCROOT} is out of date. Please run hack/update-generated-docs.sh" + echo "Generated docs are out of date. Please run hack/update-generated-docs.sh" exit 1 fi - -COMPROOT="${KUBE_ROOT}/contrib/completions" -TMP_COMPROOT="${KUBE_ROOT}/contrib/completions_tmp" -cp -a "${COMPROOT}" "${TMP_COMPROOT}" -kube::util::gen-doc "${genbashcomp}" "${TMP_COMPROOT}" "bash/" -diff -Naupr "${COMPROOT}" "${TMP_COMPROOT}" && ret=0 || ret=$? -rm -rf ${TMP_COMPROOT} -if [ $ret -eq 0 ] -then - echo "${COMPROOT} up to date." -else - echo "${COMPROOT} is out of date. Please run hack/update-generated-docs.sh" - echo "If you did not make a change to kubectl or its dependencies," - echo "run 'make clean' and retry this command." - exit 1 -fi - # ex: ts=2 sw=2 et filetype=sh diff --git a/hack/lib/util.sh b/hack/lib/util.sh index 029ca02edf2..ce80333ee64 100755 --- a/hack/lib/util.sh +++ b/hack/lib/util.sh @@ -155,60 +155,49 @@ kube::util::wait-for-jobs() { return ${fail} } -# 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 base_dest="$(kube::util::realpath $2)" - local relative_doc_dest="$(echo $3 | sed 's/\/$//')" - local dest="${base_dest}/${relative_doc_dest}" - local skipprefix="${4:-}" +# Run all known doc generators (today gendocs, genman, and genbashcomp for kubectl) +# $1 is the directory to put those generated documents +kube::util::gen-docs() { + local dest="$1" + + # Find binary + gendocs=$(kube::util::find-binary "gendocs") + genman=$(kube::util::find-binary "genman") + genbashcomp=$(kube::util::find-binary "genbashcomp") + + mkdir -p "${dest}/docs/user-guide/kubectl/" + "${gendocs}" "${dest}/docs/user-guide/kubectl/" + mkdir -p "${dest}/docs/man/man1/" + "${genman}" "${dest}/docs/man/man1/" + mkdir -p "${dest}/contrib/completions/bash/" + "${genbashcomp}" "${dest}/contrib/completions/bash/" - # 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 -p "${tmpdir}" - # generate the new files - ${cmd} "${tmpdir}" # create the list of generated files - ls "${tmpdir}" | LC_ALL=C sort > "${tmpdir}/.files_generated" + pushd "${dest}" > /dev/null + touch .generated_docs + find -type f | cut -sd / -f 2- | LC_ALL=C sort > .generated_docs + popd > /dev/null while read file; do - # Don't add analytics link to generated .md files -- that is done (and - # checked) by mungedocs. - - # Remove all old generated files from the destination - if [[ -e "${tmpdir}/${file}" ]]; then - local original generated + # Copy out of KUBE_ROOT if we didn't really change anything + if [[ -e "${dest}/${file}" && -e "${KUBE_ROOT}/${file}" ]]; then # Filter all munges from original content. - original=$(cat "${dest}/${file}" | sed '/^