github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-09-09 05:01:46 +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

45
hack/lib/util.sh
View File

@@ -208,27 +208,34 @@ kube::util::gen-docs() {
touch .generated_docs
find . -type f | cut -sd / -f 2- | LC_ALL=C sort > .generated_docs
popd > /dev/null
}
while read file; do
# 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 "${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 >/dev/null <(echo "${original}") <(echo "${generated}"); then
# actual contents same, overwrite generated with original.
cp "${KUBE_ROOT}/${file}" "${dest}/${file}"
# Puts a placeholder for every generated doc. This makes the link checker work.
kube::util::set-placeholder-gen-docs() {
local list_file="${KUBE_ROOT}/.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
fi
done <"${KUBE_ROOT}/.generated_docs"
done <"${list_file}"
# The .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() {
if [ -e "${KUBE_ROOT}/.generated_docs" ]; then
# remove all of the old docs; we don't want to check them in.
while read file; do
rm "${KUBE_ROOT}/${file}" 2>/dev/null || true
done <"${KUBE_ROOT}/.generated_docs"
# The .generated_docs file lists itself, so we don't need to explicitly
# delete it.
fi
}
# Takes a path $1 to traverse for md files to append the ga-beacon tracking