From a8e2f6e9c83a9b5d3d31755338c81606af78267b Mon Sep 17 00:00:00 2001 From: Jeff Lowdermilk Date: Thu, 23 Apr 2015 14:21:13 -0700 Subject: [PATCH] Add examples for kubectl describe, and make gendocs less spammy Makes hack/{run/verify}-gendocs.sh ignore generated-timestamp-only changes so minor changes to kubectl don't have to touch the entire set of md docs. --- docs/kubectl_describe.md | 14 ++++++++++++-- docs/man/man1/kubectl-describe.1 | 15 +++++++++++++++ hack/lib/util.sh | 28 ++++++++++++++++++++-------- hack/run-gendocs.sh | 8 +------- hack/verify-gendocs.sh | 6 ------ pkg/kubectl/cmd/describe.go | 7 ++++++- 6 files changed, 54 insertions(+), 24 deletions(-) diff --git a/docs/kubectl_describe.md b/docs/kubectl_describe.md index 165f7b79197..71c8c778030 100644 --- a/docs/kubectl_describe.md +++ b/docs/kubectl_describe.md @@ -11,7 +11,17 @@ This command joins many API calls together to form a detailed description of a given resource. ``` -kubectl describe RESOURCE ID +kubectl describe (RESOURCE NAME | RESOURCE/NAME) +``` + +### Examples + +``` +// Describe a node +$ kubectl describe nodes kubernetes-minion-emt8.c.myproject.internal + +// Describe a pod +$ kubectl describe pods/nginx ``` ### Options @@ -53,4 +63,4 @@ kubectl describe RESOURCE ID ### SEE ALSO * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager -###### Auto generated by spf13/cobra at 2015-04-23 00:47:55.40003297 +0000 UTC +###### Auto generated by spf13/cobra at 2015-04-23 21:21:05.485819349 +0000 UTC diff --git a/docs/man/man1/kubectl-describe.1 b/docs/man/man1/kubectl-describe.1 index c28d455f35d..38b2e3ba9a1 100644 --- a/docs/man/man1/kubectl-describe.1 +++ b/docs/man/man1/kubectl-describe.1 @@ -128,6 +128,21 @@ given resource. comma\-separated list of pattern=N settings for file\-filtered logging +.SH EXAMPLE +.PP +.RS + +.nf +// Describe a node +$ kubectl describe nodes kubernetes\-minion\-emt8.c.myproject.internal + +// Describe a pod +$ kubectl describe pods/nginx + +.fi +.RE + + .SH SEE ALSO .PP \fBkubectl(1)\fP, diff --git a/hack/lib/util.sh b/hack/lib/util.sh index abc786fa12b..5d286101b9b 100644 --- a/hack/lib/util.sh +++ b/hack/lib/util.sh @@ -119,17 +119,13 @@ kube::util::wait-for-jobs() { return ${fail} } -# takes a binary to run $1 and then copies the results to $2 +# 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 dest="$2" - - # remove all old generated file from the destination - for file in $(cat "${dest}/.files_generated" 2>/dev/null); do - set +e - rm "${dest}/${file}" - set -e - done + local skipprefix="${3:-}" # 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 @@ -139,6 +135,22 @@ kube::util::gen-doc() { ${cmd} "${tmpdir}" # create the list of generated files ls "${tmpdir}" | LC_ALL=C sort > "${tmpdir}/.files_generated" + + # remove all old generated file from the destination + while read file; do + if [[ -e "${tmpdir}/${file}" && -n "${skipprefix}" ]]; then + local original generated + original=$(grep -v "^${skipprefix}" "${dest}/${file}") || : + generated=$(grep -v "^${skipprefix}" "${tmpdir}/${file}") || : + if [[ "${original}" == "${generated}" ]]; then + # overwrite generated with original. + mv "${dest}/${file}" "${tmpdir}/${file}" + fi + else + rm "${dest}/${file}" || true + fi + done <"${dest}/.files_generated" + # put the new generated file into the destination find "${tmpdir}" -exec rsync -pt {} "${dest}" \; >/dev/null #cleanup diff --git a/hack/run-gendocs.sh b/hack/run-gendocs.sh index f6c954d52d4..301a9edf763 100755 --- a/hack/run-gendocs.sh +++ b/hack/run-gendocs.sh @@ -24,12 +24,6 @@ source "${KUBE_ROOT}/hack/lib/init.sh" kube::golang::setup_env "${KUBE_ROOT}/hack/build-go.sh" cmd/gendocs cmd/genman cmd/genbashcomp -# Get the absolute path of the directory component of a file, i.e. the -# absolute path of the dirname of $1. -get_absolute_dirname() { - echo "$(cd "$(dirname "$1")" && pwd)" -} - # Find binary gendocs=$(kube::util::find-binary "gendocs") genman=$(kube::util::find-binary "genman") @@ -45,7 +39,7 @@ if [[ ! -x "$gendocs" || ! -x "$genman" || ! -x "$genbashcomp" ]]; then exit 1 fi -kube::util::gen-doc "${gendocs}" "${KUBE_ROOT}/docs/" +kube::util::gen-doc "${gendocs}" "${KUBE_ROOT}/docs/" '###### 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/" diff --git a/hack/verify-gendocs.sh b/hack/verify-gendocs.sh index eca56664aee..37b807248f5 100755 --- a/hack/verify-gendocs.sh +++ b/hack/verify-gendocs.sh @@ -24,12 +24,6 @@ source "${KUBE_ROOT}/hack/lib/init.sh" kube::golang::setup_env "${KUBE_ROOT}/hack/build-go.sh" cmd/gendocs cmd/genman cmd/genbashcomp -# Get the absolute path of the directory component of a file, i.e. the -# absolute path of the dirname of $1. -get_absolute_dirname() { - echo "$(cd "$(dirname "$1")" && pwd)" -} - gendocs=$(kube::util::find-binary "gendocs") genman=$(kube::util::find-binary "genman") genbashcomp=$(kube::util::find-binary "genbashcomp") diff --git a/pkg/kubectl/cmd/describe.go b/pkg/kubectl/cmd/describe.go index 0b19931332c..eb88e5e5e90 100644 --- a/pkg/kubectl/cmd/describe.go +++ b/pkg/kubectl/cmd/describe.go @@ -29,12 +29,17 @@ import ( func NewCmdDescribe(f *cmdutil.Factory, out io.Writer) *cobra.Command { cmd := &cobra.Command{ - Use: "describe RESOURCE ID", + Use: "describe (RESOURCE NAME | RESOURCE/NAME)", Short: "Show details of a specific resource", Long: `Show details of a specific resource. This command joins many API calls together to form a detailed description of a given resource.`, + Example: `// Describe a node +$ kubectl describe nodes kubernetes-minion-emt8.c.myproject.internal + +// Describe a pod +$ kubectl describe pods/nginx`, Run: func(cmd *cobra.Command, args []string) { err := RunDescribe(f, out, cmd, args) cmdutil.CheckErr(err)