update API docs and refdocs generation script (#279)

* fix up refdocs script Signed-off-by: Tessa Pham <[email protected]> * update API docs Signed-off-by: Tessa Pham <[email protected]> --------- Signed-off-by: Tessa Pham <[email protected]>
kserve · Aug 15, 2023 · eadf13d · eadf13d
1 parent 61f6ec4
commit eadf13d
Show file tree

Hide file tree

Showing 2 changed files with 166 additions and 349 deletions.
diff --git a/docs/hack/gen-api-reference-docs.sh b/docs/hack/gen-api-reference-docs.sh
@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
 #
-#  Before running this script,
-#    1. unset GOPATH
-#    2. set KSERVE_COMMIT
-#
-#  Usage: ./gen-api-reference-docs.sh
+# Before running this script, set KSERVE_COMMIT if building docs from upstream.
+# To test or build from local changes, comment out KSERVE_COMMIT and
+# clone_at_commit() lines.
+
+# Usage: ./gen-api-reference-docs.sh
 
 
 set -euo pipefail
@@ -22,7 +22,8 @@ KSERVE_COMMIT="${KSERVE_COMMIT:?specify the \$KSERVE_COMMIT variable}"
 KSERVE_OUT_FILE="api.md"
 
 cleanup_refdocs_root=
-cleanup_repo_clone_root=
+cleanup_gopath_root=
+cleanup_out_root=
 trap cleanup EXIT
 
 log() {
@@ -40,7 +41,7 @@ install_go_bin() {
     (
         cd "$(mktemp -d)"
         go mod init tmp
-        go get -u "$pkg"
+        go install "$pkg"
     )
 }
 
@@ -62,17 +63,16 @@ clone_at_commit() {
 }
 
 gen_refdocs() {
-    local refdocs_bin gopath out_file repo_root api_dir
+    local refdocs_bin template_dir out_file repo_root api_dir
     refdocs_bin="$1"
-    gopath="$2"
-    template_dir="$3"
-    out_file="$4"
-    repo_root="$5"
-    api_dir="$6"
+    template_dir="$2"
+    out_file="$3"
+    repo_root="$4"
+    api_dir="$5"
 
     (
         cd "${repo_root}"
-        env GOPATH="${gopath}" "${refdocs_bin}" \
+        "${refdocs_bin}" \
             -out-file "${out_file}" \
             -api-dir "${api_dir}" \
             -template-dir "${template_dir}" \
@@ -85,16 +85,17 @@ cleanup() {
         echo "Cleaning up tmp directory: ${cleanup_refdocs_root}"
         rm -rf -- "${cleanup_refdocs_root}"
     fi
-    if [ -d "${cleanup_repo_clone_root}" ]; then
-        echo "Cleaning up tmp directory: ${cleanup_repo_clone_root}"
-        rm -rf -- "${cleanup_repo_clone_root}"
+    if [ -d "${cleanup_gopath_root}" ]; then
+        echo "Cleaning up tmp directory: ${cleanup_gopath_root}"
+        rm -rf -- "${cleanup_gopath_root}"
+    fi
+    if [ -d "${cleanup_out_root}" ]; then
+        echo "Cleaning up tmp directory: ${cleanup_out_root}"
+        rm -rf -- "${cleanup_out_root}"
     fi
 }
 
 main() {
-    if [[ -n "${GOPATH:-}" ]]; then
-        fail "GOPATH should not be set."
-    fi
     if ! command -v "go" 1>/dev/null ; then
         fail "\"go\" is not in PATH"
     fi
@@ -110,23 +111,25 @@ main() {
     git clone --quiet --depth=1 "${REFDOCS_REPO}" "${refdocs_dir}"
     template_dir="${refdocs_dir}/template"
     # install bin
+    gopath="$(mktemp -d)"
+    cleanup_gopath_root="${gopath}"
+    env GOPATH="${gopath}"
     install_go_bin "${REFDOCS_PKG}@${REFDOCS_VER}"
     # move bin to final location
     refdocs_bin="${refdocs_dir}/refdocs"
-    refdocs_bin_expected="$(go env GOPATH)/bin/$(basename ${REFDOCS_PKG})"
+    refdocs_bin_expected="${GOPATH}/bin/$(basename ${REFDOCS_PKG})"
     mv "${refdocs_bin_expected}" "${refdocs_bin}"
     [[ ! -f "${refdocs_bin}" ]] && fail "refdocs failed to install"
 
-    local clone_root out_dir
-    clone_root="$(mktemp -d)"
-    cleanup_repo_clone_root="${clone_root}"
+    local out_dir kserve_root
     out_dir="$(mktemp -d)"
-
-    local kserve_root
-    kserve_root="${clone_root}/src/${KSERVE_IMPORT_PATH}"
+    cleanup_out_root="${out_dir}"
+    kserve_root="${GOPATH}/src/${KSERVE_IMPORT_PATH}"
+    # use local path if building docs from local changes
+    # kserve_root="/Users/hpham111/git/kserve"
     clone_at_commit "https://${KSERVE_REPO}.git" "${KSERVE_COMMIT}" \
         "${kserve_root}"
-    gen_refdocs "${refdocs_bin}" "${clone_root}" "${template_dir}" \
+    gen_refdocs "${refdocs_bin}" "${template_dir}" \
         "${out_dir}/${KSERVE_OUT_FILE}" "${kserve_root}" "./pkg/apis/serving/v1beta1"
 
     cp "${out_dir}/${KSERVE_OUT_FILE}" "$SCRIPTDIR/../reference/${KSERVE_OUT_FILE}"
@@ -135,4 +138,4 @@ main() {
     # git apply $SCRIPTDIR/patches/*.patch
 }
 
-main "$@"
+main "$@"