mirror of https://github.com/knative/docs.git
api-reference: Add API reference docs (#714)
Generated with https://github.com/ahmetb/gen-crd-api-reference-docs and this patch includes the script to self-serve this process. I hope to improve this stuff in the future, for now it works fine. Fixes #636. Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>
This commit is contained in:
Ahmet Alp Balkan
Knative Prow Robot
parent
0e9baf68aa
commit
df7c2b5dff
|
|
@ -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 "$@"
|
||||||
|
|
@ -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
|
||||||
|
}
|
||||||
|
|
@ -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)
|
||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,165 @@
|
||||||
|
#!/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="reference/serving.md"
|
||||||
|
|
||||||
|
KNATIVE_BUILD_REPO="github.com/knative/build"
|
||||||
|
KNATIVE_BUILD_COMMIT="v0.2.0"
|
||||||
|
KNATIVE_BUILD_OUT_FILE="reference/build.md"
|
||||||
|
|
||||||
|
KNATIVE_EVENTING_REPO="github.com/knative/eventing"
|
||||||
|
KNATIVE_EVENTING_COMMIT="v0.2.1"
|
||||||
|
KNATIVE_EVENTING_OUT_FILE="reference/eventing/eventing.md"
|
||||||
|
|
||||||
|
KNATIVE_EVENTING_SOURCES_REPO="github.com/knative/eventing-sources"
|
||||||
|
KNATIVE_EVENTING_SOURCES_COMMIT="v0.2.1"
|
||||||
|
KNATIVE_EVENTING_SOURCES_OUT_FILE="reference/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}/knative-refdocs-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
|
||||||
|
|
||||||
|
# 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/."
|
||||||
|
if command -v open >/dev/null; then
|
||||||
|
open "${clone_root}/out/"
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
main "$@"
|
||||||
|
|
@ -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
|
||||||
|
}
|
||||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue