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