Adding a script to update federation API reference docs

209d544b · nikhiljindal · a954ff18 · 209d544b · 209d544b · 209d544b
Commit 209d544b authored Aug 30, 2016 by nikhiljindal
4 changed files
--- a/hack/lib/swagger.sh
+++ b/hack/lib/swagger.sh
@@ -15,6 +15,13 @@
 # limitations under the License.

 # Contains swagger related util functions.
+#
+set -o errexit
+set -o nounset
+set -o pipefail
+
+# The root of the build/dist directory
+KUBE_ROOT="$(cd "$(dirname "${BASH_SOURCE}")/../.." && pwd -P)"

 # Generates types_swagger_doc_generated file for the given group version.
 # $1: Name of the group version
@@ -54,3 +61,94 @@ EOF
  gofmt -w -s "$TMPFILE"
  mv "$TMPFILE" ""${gv_dir}"/types_swagger_doc_generated.go"
 }
+
+# Generates API reference docs for the given API group versions.
+# Required env vars:
+#   GROUP_VERSIONS: Array of group versions to be included in the reference
+#   docs.
+#   GV_DIRS: Array of root directories for those group versions.
+# Input vars:
+#   $1: Root directory path for swagger spec
+#   $2: Root directory path where the reference docs should be generated.
+kube::swagger::gen_api_ref_docs() {
+    : "${GROUP_VERSIONS?Must set GROUP_VERSIONS env var}"
+    : "${GV_DIRS?Must set GV_DIRS env var}"
+
+  echo "Generating API reference docs for group versions: ${GROUP_VERSIONS[@]}, at dirs: ${GV_DIRS[@]}"
+  GROUP_VERSIONS=(${GROUP_VERSIONS[@]})
+  GV_DIRS=(${GV_DIRS[@]})
+  local swagger_spec_path=${1}
+  local output_dir=${2}
+  echo "Reading swagger spec from: ${swagger_spec_path}"
+  echo "Generating the docs at: ${output_dir}"
+
+  # Use REPO_DIR if provided so we can set it to the host-resolvable path
+  # to the repo root if we are running this script from a container with
+  # docker mounted in as a volume.
+  # We pass the host output dir as the source dir to `docker run -v`, but use
+  # the regular one to compute diff (they will be the same if running this
+  # test on the host, potentially different if running in a container).
+  local repo_dir=${REPO_DIR:-"${KUBE_ROOT}"}
+  local tmp_subpath="_output/generated_html"
+  local output_tmp_in_host="${repo_dir}/${tmp_subpath}"
+  local output_tmp="${KUBE_ROOT}/${tmp_subpath}"
+
+  echo "Generating api reference docs at ${output_tmp}"
+
+  for ver in "${GROUP_VERSIONS[@]}"; do
+    mkdir -p "${output_tmp}/${ver}"
+  done
+
+  user_flags="-u $(id -u)"
+  if [[ $(uname) == "Darwin" ]]; then
+    # mapping in a uid from OS X doesn't make any sense
+    user_flags=""
+  fi
+
+  for i in "${!GROUP_VERSIONS[@]}"; do
+    local ver=${GROUP_VERSIONS[i]}
+    local dir=${GV_DIRS[i]}
+    local tmp_in_host="${output_tmp_in_host}/${ver}"
+    local register_file="${dir}/register.go"
+    local swagger_json_name="$(kube::util::gv-to-swagger-name "${ver}")"
+
+    docker run ${user_flags} \
+      --rm -v "${tmp_in_host}":/output:z \
+      -v "${swagger_spec_path}":/swagger-source:z \
+      -v "${register_file}":/register.go:z \
+      --net=host -e "https_proxy=${KUBERNETES_HTTPS_PROXY:-}" \
+      gcr.io/google_containers/gen-swagger-docs:v8 \
+      "${swagger_json_name}"
+  done
+
+  # Check if we actually changed anything
+  pushd "${output_tmp}" > /dev/null
+  touch .generated_html
+  find . -type f | cut -sd / -f 2- | LC_ALL=C sort > .generated_html
+  popd > /dev/null
+
+  while read file; do
+    if [[ -e "${output_dir}/${file}" && -e "${output_tmp}/${file}" ]]; then
+      echo "comparing ${output_dir}/${file} with ${output_tmp}/${file}"
+      # Filter all munges from original content.
+      original=$(cat "${output_dir}/${file}")
+      generated=$(cat "${output_tmp}/${file}")
+
+      # Filter out meaningless lines with timestamps
+      original=$(echo "${original}" | grep -v "Last updated" || :)
+      generated=$(echo "${generated}" | grep -v "Last updated" || :)
+
+      # By now, the contents should be normalized and stripped of any
+      # auto-managed content.
+      if diff -B >/dev/null <(echo "${original}") <(echo "${generated}"); then
+        # actual contents same, overwrite generated with original.
+        cp "${output_dir}/${file}" "${output_tmp}/${file}"
+      fi
+    fi
+  done <"${output_tmp}/.generated_html"
+
+  echo "Moving api reference docs from ${output_tmp} to ${output_dir}"
+
+  cp -af "${output_tmp}"/* "${output_dir}"
+  rm -r "${output_tmp}"
+}
--- a/hack/update-api-reference-docs.sh
+++ b/hack/update-api-reference-docs.sh
 #!/bin/bash

-# Copyright 2015 The Kubernetes Authors.
+# Copyright 2016 The Kubernetes Authors.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -25,86 +25,21 @@ echo "Note: This assumes that swagger spec has been updated. Please run hack/upd

 KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
 source "${KUBE_ROOT}/hack/lib/init.sh"
+source "${KUBE_ROOT}/hack/lib/swagger.sh"
 kube::golang::setup_env

-DEFAULT_OUTPUT="${KUBE_ROOT}/docs/api-reference"
-OUTPUT=${1:-${DEFAULT_OUTPUT}}
-# Use REPO_DIR if provided so we can set it to the host-resolvable path
-# to the repo root if we are running this script from a container with
-# docker mounted in as a volume.
-# We pass the host output dir as the source dir to `docker run -v`, but use
-# the regular one to compute diff (they will be the same if running this
-# test on the host, potentially different if running in a container).
 REPO_DIR=${REPO_DIR:-"${KUBE_ROOT}"}
-TMP_SUBPATH="_output/generated_html"
-OUTPUT_TMP_IN_HOST="${REPO_DIR}/${TMP_SUBPATH}"
-OUTPUT_TMP="${KUBE_ROOT}/${TMP_SUBPATH}"
-
-echo "Generating api reference docs at ${OUTPUT_TMP}"
-
-DEFAULT_GROUP_VERSIONS="v1 extensions/v1beta1 batch/v1 autoscaling/v1 certificates/v1alpha1"
-VERSIONS=${VERSIONS:-$DEFAULT_GROUP_VERSIONS}
-for ver in $VERSIONS; do
-  mkdir -p "${OUTPUT_TMP}/${ver}"
-done
-
-SWAGGER_PATH="${REPO_DIR}/api/swagger-spec/"
-
-echo "Reading swagger spec from: ${SWAGGER_PATH}"
-
-user_flags="-u $(id -u)"
-if [[ $(uname) == "Darwin" ]]; then
-  # mapping in a uid from OS X doesn't make any sense
-  user_flags=""
-fi
+DEFAULT_OUTPUT="${REPO_DIR}/docs/api-reference"
+OUTPUT=${1:-${DEFAULT_OUTPUT}}

-for ver in $VERSIONS; do
-  TMP_IN_HOST="${OUTPUT_TMP_IN_HOST}/${ver}"
-  if [[ ${ver} == "v1" ]]; then
-    REGISTER_FILE="${REPO_DIR}/pkg/api/${ver}/register.go"
-  else
-    REGISTER_FILE="${REPO_DIR}/pkg/apis/${ver}/register.go"
-  fi
-  SWAGGER_JSON_NAME="$(kube::util::gv-to-swagger-name "${ver}")"
+SWAGGER_SPEC_PATH="${REPO_DIR}/api/swagger-spec"

-  docker run ${user_flags} \
-    --rm -v "${TMP_IN_HOST}":/output:z \
-    -v "${SWAGGER_PATH}":/swagger-source:z \
-    -v "${REGISTER_FILE}":/register.go:z \
-    --net=host -e "https_proxy=${KUBERNETES_HTTPS_PROXY:-}" \
-    gcr.io/google_containers/gen-swagger-docs:v8 \
-    "${SWAGGER_JSON_NAME}"
+GROUP_VERSIONS=("v1" "extensions/v1beta1" "batch/v1" "autoscaling/v1" "certificates/v1alpha1")
+GV_DIRS=()
+for gv in "${GROUP_VERSIONS[@]}"; do
+  GV_DIRS+=("${REPO_DIR}/pkg/$(kube::util::group-version-to-pkg-path "${gv}")")
 done

-# Check if we actually changed anything
-pushd "${OUTPUT_TMP}" > /dev/null
-touch .generated_html
-find . -type f | cut -sd / -f 2- | LC_ALL=C sort > .generated_html
-popd > /dev/null
-
-while read file; do
-  if [[ -e "${OUTPUT}/${file}" && -e "${OUTPUT_TMP}/${file}" ]]; then
-    echo "comparing ${OUTPUT}/${file} with ${OUTPUT_TMP}/${file}"
-    # Filter all munges from original content.
-    original=$(cat "${OUTPUT}/${file}")
-    generated=$(cat "${OUTPUT_TMP}/${file}")
-
-    # Filter out meaningless lines with timestamps
-    original=$(echo "${original}" | grep -v "Last updated" || :)
-    generated=$(echo "${generated}" | grep -v "Last updated" || :)
-
-    # By now, the contents should be normalized and stripped of any
-    # auto-managed content.
-    if diff -B >/dev/null <(echo "${original}") <(echo "${generated}"); then
-      # actual contents same, overwrite generated with original.
-      cp "${OUTPUT}/${file}" "${OUTPUT_TMP}/${file}"
-    fi
-  fi
-done <"${OUTPUT_TMP}/.generated_html"
-
-echo "Moving api reference docs from ${OUTPUT_TMP} to ${OUTPUT}"
-
-cp -af "${OUTPUT_TMP}"/* "${OUTPUT}"
-rm -r "${OUTPUT_TMP}"
+GROUP_VERSIONS="${GROUP_VERSIONS[@]}" GV_DIRS="${GV_DIRS[@]}" kube::swagger::gen_api_ref_docs "${SWAGGER_SPEC_PATH}" "${OUTPUT}"

 # ex: ts=2 sw=2 et filetype=sh
--- a/hack/update-federation-api-reference-docs.sh
+++ b/hack/update-federation-api-reference-docs.sh
+#!/bin/bash
+
+# Copyright 2016 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Generates updated api-reference docs from the latest swagger spec for
+# federation apiserver. The docs are generated at federation/docs/api-reference
+# Usage: ./update-federation-api-reference-docs.sh <absolute output path>
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+echo "Note: This assumes that swagger spec has been updated. Please run hack/update-federation-swagger-spec.sh to ensure that."
+
+KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
+source "${KUBE_ROOT}/hack/lib/init.sh"
+source "${KUBE_ROOT}/hack/lib/swagger.sh"
+kube::golang::setup_env
+
+REPO_DIR=${REPO_DIR:-"${KUBE_ROOT}"}
+DEFAULT_OUTPUT="${REPO_DIR}/federation/docs/api-reference"
+OUTPUT=${1:-${DEFAULT_OUTPUT}}
+
+SWAGGER_SPEC_PATH="${REPO_DIR}/federation/apis/swagger-spec"
+
+GROUP_VERSIONS=("federation/v1beta1" "v1" "extensions/v1beta1")
+GV_DIRS=()
+for gv in "${GROUP_VERSIONS[@]}"; do
+  if [[ ${gv} == "federation/v1beta1" ]]; then
+    GV_DIRS+=("${REPO_DIR}/federation/$(kube::util::group-version-to-pkg-path "${gv}")")
+  else
+    GV_DIRS+=("${REPO_DIR}/pkg/$(kube::util::group-version-to-pkg-path "${gv}")")
+  fi
+done
+
+GROUP_VERSIONS="${GROUP_VERSIONS[@]}" GV_DIRS="${GV_DIRS[@]}" kube::swagger::gen_api_ref_docs "${SWAGGER_SPEC_PATH}" "${OUTPUT}"
+
+# ex: ts=2 sw=2 et filetype=sh
--- a/hack/update-federation-generated-swagger-docs.sh
+++ b/hack/update-federation-generated-swagger-docs.sh
 #!/bin/bash

-# Copyright 2015 The Kubernetes Authors.
+# Copyright 2016 The Kubernetes Authors.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -29,7 +29,11 @@ source "${KUBE_ROOT}/hack/lib/swagger.sh"
 kube::golang::setup_env

 GROUP_VERSIONS=(federation/v1beta1)
-GV_DIRS=("federation/apis/federation/v1beta1")
+GV_DIRS=()
+for gv in "${GROUP_VERSIONS[@]}"; do
+  GV_DIRS+=("federation/$(kube::util::group-version-to-pkg-path "${gv}")")
+done
+
 # To avoid compile errors, remove the currently existing files.
 for gv_dir in "${GV_DIRS[@]}"; do
  rm -f "${gv_dir}/types_swagger_doc_generated.go"