github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-09-07 12:11:43 +00:00
Code Issues Projects Releases Wiki Activity

Revamp doc generation

Browse Source 
Auto generated docs are **NO LONGER CHECKED IN**, only placeholders.

To generate them, e.g. before exporting docs, run hack/generate-docs.sh.

hack/verify-generated-docs.sh ensures that generated docs are merely the
placeholder text.

hack/update-generated-docs.sh puts the placeholder text in the proper
places.

The old munge behavior is moved into hack/{update|verify}-munge-docs.sh.
This commit is contained in:
Daniel Smith
2016-06-03 15:13:26 -07:00
parent 34dcea3037
commit 8faa88626d
8 changed files with 244 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
hack/verify-generated-docs.sh
View File

@@ -28,57 +28,29 @@ kube::golang::setup_env
cmd/genkubedocs \
cmd/genman \
cmd/genyaml \
cmd/mungedocs
# Find binary
mungedocs=$(kube::util::find-binary "mungedocs")
DOCROOT="${KUBE_ROOT}/docs/"
EXAMPLEROOT="${KUBE_ROOT}/examples/"
# 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.
# --verbose gives us output we can use for a diff.
"${mungedocs}" "--verify=true" "--verbose=true" "--upstream=${KUBE_GIT_UPSTREAM}" "--root-dir=${DOCROOT}" && ret=0 || ret=$?
if [[ $ret -eq 1 ]]; then
echo "${DOCROOT} is out of date. Please run hack/update-generated-docs.sh"
exit 1
fi
if [[ $ret -gt 1 ]]; then
echo "Error running mungedocs"
exit 1
fi
"${mungedocs}" "--verify=true" "--verbose=true" "--upstream=${KUBE_GIT_UPSTREAM}" "--root-dir=${EXAMPLEROOT}" && ret=0 || ret=$?
if [[ $ret -eq 1 ]]; then
echo "${EXAMPLEROOT} is out of date. Please run hack/update-generated-docs.sh"
exit 1
fi
if [[ $ret -gt 1 ]]; then
echo "Error running mungedocs"
exit 1
fi
federation/cmd/genfeddocs
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:"
printf '%s\n' "${needsanalytics[@]}"
ret=1
fi
if [[ $ret -eq 0 ]]
then
echo "Generated docs are up to date."
else
echo "Generated docs are out of date. Please run hack/update-generated-docs.sh"
# Verify the list matches the expected list (diff should be empty)
if [[ "$(diff ${KUBE_ROOT}/.generated_docs ${KUBE_TEMP}/.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
# ex: ts=2 sw=2 et filetype=sh
# Verify the files in the repo all contain the boilerplate instead of the actual
# content.
while read file; do
# Ignore .generated_docs-- it should not have the boilerplate!
[[ "${file}" == ".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}/.generated_docs"