docs: stop tracking placeholder documentation

The placeholder documentation introduces a couple of problems:
- it complicates the contributor-experience (forces the CI to run
N times before the contributor finds out that they need to call an .sh
script and include certain files from docs/)
- it forces CLI related pull requests for tools like kubeadm and kubectl
to require top level approval from docs/OWNERS as such PRs still need
to touch the .generated_docs file

Stop tracking the placeholder documentation by applying the
following actions:
- remove the utility set-placeholder-gen-docs()
- make verify-generated-docs.sh only generate in a temporary folder
and not match .generated_docs
- mark generate-docs.sh as an alias for update-generated-docs.sh
- remove all current placeholder files in docs folders admin, man,
user-guide, yaml
- ignore the above folders and .generated_docs in a .gitignore file

hack/autogenerated_placeholder.txt

@@ -1,3 +0,0 @@
-This file is autogenerated, but we've stopped checking such files into the
-repository to reduce the need for rebases. Please run hack/generate-docs.sh to
-populate this file.

hack/generate-docs.sh

@@ -22,28 +22,9 @@ set -o errexit
 set -o nounset
 set -o pipefail
 
-KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
-source "${KUBE_ROOT}/hack/lib/init.sh"
+KUBE_HACK_ROOT=$(dirname "${BASH_SOURCE}")
 
-kube::golang::setup_env
+echo "WARNING: hack/generate-docs.sh is an alias for hack/update-generated-docs.sh"
+echo "and will be removed in a future version."
 
-BINS=(
-	cmd/gendocs
-	cmd/genkubedocs
-	cmd/genman
-	cmd/genyaml
-)
-make -C "${KUBE_ROOT}" WHAT="${BINS[*]}"
-
-kube::util::ensure-temp-dir
-
-kube::util::gen-docs "${KUBE_TEMP}"
-
-# remove all of the old docs
-kube::util::remove-gen-docs
-
-# copy fresh docs into the repo.
-# the shopt is so that we get docs/.generated_docs from the glob.
-shopt -s dotglob
-cp -af "${KUBE_TEMP}"/* "${KUBE_ROOT}"
-shopt -u dotglob
+"${KUBE_HACK_ROOT}"/update-generated-docs.sh

hack/lib/util.sh

@@ -228,21 +228,6 @@ kube::util::gen-docs() {
   popd > /dev/null
 }
 
-# Puts a placeholder for every generated doc. This makes the link checker work.
-kube::util::set-placeholder-gen-docs() {
-  local list_file="${KUBE_ROOT}/docs/.generated_docs"
-  if [[ -e "${list_file}" ]]; then
-    # remove all of the old docs; we don't want to check them in.
-    while read file; do
-      if [[ "${list_file}" != "${KUBE_ROOT}/${file}" ]]; then
-        cp "${KUBE_ROOT}/hack/autogenerated_placeholder.txt" "${KUBE_ROOT}/${file}"
-      fi
-    done <"${list_file}"
-    # The docs/.generated_docs file lists itself, so we don't need to explicitly
-    # delete it.
-  fi
-}
-
 # Removes previously generated docs-- we don't want to check them in. $KUBE_ROOT
 # must be set.
 kube::util::remove-gen-docs() {

hack/update-generated-docs.sh

@@ -47,6 +47,3 @@ kube::util::remove-gen-docs
 shopt -s dotglob
 cp -af "${KUBE_TEMP}"/* "${KUBE_ROOT}"
 shopt -u dotglob
-
-# Replace with placeholder docs
-kube::util::set-placeholder-gen-docs

hack/verify-generated-docs.sh

@@ -33,25 +33,5 @@ make -C "${KUBE_ROOT}" WHAT="${BINS[*]}"
 
 kube::util::ensure-temp-dir
 
+# just verify the generation process
 kube::util::gen-docs "${KUBE_TEMP}"
-
-# Verify the list matches the expected list (diff should be empty)
-if ! diff "${KUBE_ROOT}/docs/.generated_docs" "${KUBE_TEMP}/docs/.generated_docs"; then
-  echo "List of generated docs doesn't match a freshly built list. Please run hack/update-generated-docs.sh"
-  exit 1
-fi
-
-# Verify the files in the repo all contain the boilerplate instead of the actual
-# content.
-while read file; do
-  # Ignore docs/.generated_docs-- it should not have the boilerplate!
-  [[ "${file}" == "docs/.generated_docs" ]] && continue
-
-  # Search for "hack/generate-docs.sh" as a proxy for the boilerplate content,
-  # since the munger adds a bunch of other stuff.
-  if [[ "$(grep "hack/generate-docs.sh" "${KUBE_ROOT}/${file}")" == "" ]]; then
-    echo "${file} doesn't seem to have the correct boilerplate content for an autogenerated file."
-    echo "Please run hack/update-generated-docs.sh"
-    exit 1
-  fi
-done <"${KUBE_ROOT}/docs/.generated_docs"