Merge pull request #13613 from eparis/rework-doc-generation

Rework automatic doc generation

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
 }
 
@@ -124,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 '/^<!-- BEGIN MUNGE:.*/,/^<!-- END MUNGE:.*/d')
-      generated=$(cat "${tmpdir}/${file}")
-      # If this function was asked to filter lines with a prefix, do so.
-      if [[ -n "${skipprefix}" ]]; then
-        original=$(echo "${original}" | grep -v "^${skipprefix}" || :)
-        generated=$(echo "${generated}" | grep -v "^${skipprefix}" || :)
-      fi
+      original=$(cat "${KUBE_ROOT}/${file}" | sed '/^<!-- BEGIN MUNGE:.*/,/^<!-- END MUNGE:.*/d')
+      generated=$(cat "${dest}/${file}")
+
+      # Filter out meaningless lines with timestamps
+      original=$(echo "${original}" | grep -v "Auto generated by spf13/cobra" || :)
+      generated=$(echo "${generated}" | grep -v "Auto generated by spf13/cobra" || :)
+
       # By now, the contents should be normalized and stripped of any
       # auto-managed content.  We also ignore whitespace here because of
       # markdown strictness fixups later in the pipeline.
-      if diff -Bw <(echo "${original}") <(echo "${generated}") > /dev/null; then
+      if diff -Bw >/dev/null <(echo "${original}") <(echo "${generated}"); then
         # actual contents same, overwrite generated with original.
-        mv "${dest}/${file}" "${tmpdir}/${file}"
+        cp "${KUBE_ROOT}/${file}" "${dest}/${file}"
       fi
-    else
-      rm "${dest}/${file}" || true
     fi
-  done <"${dest}/.files_generated"
-
-  # put the new generated file into the destination
-  # the shopt is so that we get .files_generated from the glob.
-  shopt -s dotglob
-  cp -af "${tmpdir}"/* "${dest}"
-  shopt -u dotglob
-
-  #cleanup
-  rm -rf "${tmpdir}"
+  done <"${KUBE_ROOT}/.generated_docs"
 }
 
 # Takes a path $1 to traverse for md files to append the ga-beacon tracking