api-reference: Add API reference docs

hack/gen-api-reference-docs.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+#
+# This script is for generating API reference docs for Knative components.
+
+# Copyright 2018 Knative 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.
+set -euo pipefail
+
+SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+[[ -n "${DEBUG:-}" ]] && set -x
+
+REFDOCS_PKG="github.com/ahmetb/gen-crd-api-reference-docs"
+REFDOCS_REPO="https://${REFDOCS_PKG}.git"
+REFDOCS_VER="5c208a6"
+
+KNATIVE_SERVING_REPO="github.com/knative/serving"
+KNATIVE_SERVING_COMMIT="v0.2.3"
+KNATIVE_SERVING_OUT_FILE="serving.md"
+
+KNATIVE_BUILD_REPO="github.com/knative/build"
+KNATIVE_BUILD_COMMIT="v0.2.0"
+KNATIVE_BUILD_OUT_FILE="build.md"
+
+KNATIVE_EVENTING_REPO="github.com/knative/eventing"
+KNATIVE_EVENTING_COMMIT="v0.2.1"
+KNATIVE_EVENTING_OUT_FILE="eventing/eventing.md"
+
+KNATIVE_EVENTING_SOURCES_REPO="github.com/knative/eventing-sources"
+KNATIVE_EVENTING_SOURCES_COMMIT="v0.2.1"
+KNATIVE_EVENTING_SOURCES_OUT_FILE="eventing/eventing-sources.md"
+
+log() {
+    echo "$@" >&2
+}
+
+fail() {
+    log "error: $*"
+    exit 1
+}
+
+install_go_bin() {
+    local pkg
+    pkg="$1"
+    (
+        cd "$(mktemp -d)"
+        go mod init tmp
+        go get -u "$pkg"
+        # will be downloaded to "$(go env GOPATH)/bin/$(basename $pkg)"
+    )
+}
+
+repo_tarball_url() {
+    local repo commit
+    repo="$1"
+    commit="$2"
+    echo "https://$repo/archive/$commit.tar.gz"
+}
+
+dl_and_extract() {
+    # TODO(ahmetb) remove this function. no longer dl'ing tarballs since they
+    # won't have a .git dir to infer the commit ID from to be used by refdocs.
+    local url dest
+    url="$1"
+    dest="$2"
+    mkdir -p "${dest}"
+    curl -sSLf "$url" | tar zxf - --directory="$dest"  --strip 1
+}
+
+clone_at_commit() {
+    local repo commit dest
+    repo="$1"
+    commit="$2"
+    dest="$3"
+    mkdir -p "${dest}"
+    git clone "${repo}" "${dest}"
+    git --git-dir="${dest}/.git" --work-tree="${dest}" checkout --detach --quiet "${commit}"
+}
+
+gen_refdocs() {
+    local refdocs_bin gopath out_file repo_root
+    refdocs_bin="$1"
+    gopath="$2"
+    out_file="$3"
+    repo_root="$4"
+
+    (
+        cd "${repo_root}"
+        env GOPATH="${gopath}" "${refdocs_bin}" \
+            -out-file "${gopath}/out/${out_file}" \
+            -api-dir "./pkg/apis" \
+            -config "${SCRIPTDIR}/reference-docs-gen-config.json"
+    )
+}
+
+
+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
+    if ! command -v "git" 1>/dev/null ; then
+        fail "\"git\" is not in PATH"
+    fi
+
+    # install and place the refdocs tool
+    local refdocs_bin refdocs_bin_expected refdocs_dir
+    refdocs_dir="$(mktemp -d)"
+    refdocs_bin="${refdocs_dir}/refdocs"
+    # clone repo for ./templates
+    git clone --quiet --depth=1 "${REFDOCS_REPO}" "${refdocs_dir}"
+    # install bin
+    install_go_bin "${REFDOCS_PKG}@${REFDOCS_VER}"
+    # move bin to final location
+    refdocs_bin_expected="$(go env GOPATH)/bin/$(basename ${REFDOCS_PKG})"
+    mv "${refdocs_bin_expected}" "${refdocs_bin}"
+    [[ ! -f "${refdocs_bin}" ]] && fail "refdocs failed to install"
+
+    local clone_root
+    clone_root="$(mktemp -d)"
+
+    local knative_serving_root
+    knative_serving_root="${clone_root}/src/${KNATIVE_SERVING_REPO}"
+    clone_at_commit "https://${KNATIVE_SERVING_REPO}.git" "${KNATIVE_SERVING_COMMIT}" \
+        "${knative_serving_root}"
+    gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_SERVING_OUT_FILE}" \
+        "${knative_serving_root}"
+
+    local knative_build_root
+    knative_build_root="${clone_root}/src/${KNATIVE_BUILD_REPO}"
+    clone_at_commit "https://${KNATIVE_BUILD_REPO}.git" "${KNATIVE_BUILD_COMMIT}" \
+        "${knative_build_root}"
+    gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_BUILD_OUT_FILE}" \
+        "${knative_build_root}"
+
+    local knative_eventing_root
+    knative_eventing_root="${clone_root}/src/${KNATIVE_EVENTING_REPO}"
+    clone_at_commit "https://${KNATIVE_EVENTING_REPO}.git" "${KNATIVE_EVENTING_COMMIT}" \
+        "${knative_eventing_root}"
+    gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_EVENTING_OUT_FILE}" \
+        "${knative_eventing_root}"
+
+    local knative_eventing_sources_root
+    knative_eventing_sources_root="${clone_root}/src/${KNATIVE_EVENTING_SOURCES_REPO}"
+    clone_at_commit "https://${KNATIVE_EVENTING_SOURCES_REPO}.git" "${KNATIVE_EVENTING_SOURCES_COMMIT}" \
+        "${knative_eventing_sources_root}"
+    gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_EVENTING_SOURCES_OUT_FILE}" \
+        "${knative_eventing_sources_root}"
+
+    log "Generated files written to ${clone_root}/out/."
+    log "Copy the files in reference/ directory to knative/docs."
+    if command -v open >/dev/null; then
+        open "${clone_root}/out/"
+    fi
+}
+
+main "$@"

hack/reference-docs-gen-config.json

@@ -0,0 +1,28 @@
+{
+    "hideMemberFields": [
+        "TypeMeta"
+    ],
+    "hideTypePatterns": [
+        "ParseError$",
+        "List$"
+    ],
+    "externalPackages": [
+        {
+            "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
+            "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
+        },
+        {
+            "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/",
+            "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
+        },
+        {
+            "typeMatchPrefix": "^github\\.com/knative/pkg/apis/duck/",
+            "docsURLTemplate": "https://godoc.org/github.com/knative/pkg/apis/duck/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}"
+        }
+    ],
+    "typeDisplayNamePrefixOverrides": {
+        "k8s.io/api/": "Kubernetes ",
+        "k8s.io/apimachinery/pkg/apis/": "Kubernetes "
+    },
+    "markdownDisabled": false
+}

reference/README.md

@@ -0,0 +1,6 @@
+# Knative API Reference documentation
+
+- [Serving API](serving.md)
+- [Build API](build.md)
+- [Eventing API](eventing/eventing.md)
+- [Event Sources API](eventing/eventing-sources.md)