Skip to content

Commit df7c2b5

Browse files
ahmetbknative-prow-robot
ahmetb
authored and
knative-prow-robot
committed
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 <[email protected]>
1 parent 0e9baf6 commit df7c2b5

File tree

9 files changed

+6894
-0
lines changed

9 files changed

+6894
-0
lines changed

‎hack/gen-api-reference-docs.sh‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
#!/usr/bin/env bash
2+
#
3+
# This script is for generating API reference docs for Knative components.
4+
5+
# Copyright 2018 Knative authors
6+
#
7+
# Licensed under the Apache License, Version 2.0 (the "License");
8+
# you may not use this file except in compliance with the License.
9+
# You may obtain a copy of the License at
10+
#
11+
# http://www.apache.org/licenses/LICENSE-2.0
12+
#
13+
# Unless required by applicable law or agreed to in writing, software
14+
# distributed under the License is distributed on an "AS IS" BASIS,
15+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
# See the License for the specific language governing permissions and
17+
# limitations under the License.
18+
set -euo pipefail
19+
20+
SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
21+
[[ -n "${DEBUG:-}" ]] && set -x
22+
23+
REFDOCS_PKG="github.com/ahmetb/gen-crd-api-reference-docs"
24+
REFDOCS_REPO="https://${REFDOCS_PKG}.git"
25+
REFDOCS_VER="5c208a6"
26+
27+
KNATIVE_SERVING_REPO="github.com/knative/serving"
28+
KNATIVE_SERVING_COMMIT="v0.2.3"
29+
KNATIVE_SERVING_OUT_FILE="serving.md"
30+
31+
KNATIVE_BUILD_REPO="github.com/knative/build"
32+
KNATIVE_BUILD_COMMIT="v0.2.0"
33+
KNATIVE_BUILD_OUT_FILE="build.md"
34+
35+
KNATIVE_EVENTING_REPO="github.com/knative/eventing"
36+
KNATIVE_EVENTING_COMMIT="v0.2.1"
37+
KNATIVE_EVENTING_OUT_FILE="eventing/eventing.md"
38+
39+
KNATIVE_EVENTING_SOURCES_REPO="github.com/knative/eventing-sources"
40+
KNATIVE_EVENTING_SOURCES_COMMIT="v0.2.1"
41+
KNATIVE_EVENTING_SOURCES_OUT_FILE="eventing/eventing-sources.md"
42+
43+
log() {
44+
echo "$@" >&2
45+
}
46+
47+
fail() {
48+
log "error: $*"
49+
exit 1
50+
}
51+
52+
install_go_bin() {
53+
local pkg
54+
pkg="$1"
55+
(
56+
cd "$(mktemp -d)"
57+
go mod init tmp
58+
go get -u "$pkg"
59+
# will be downloaded to "$(go env GOPATH)/bin/$(basename $pkg)"
60+
)
61+
}
62+
63+
repo_tarball_url() {
64+
local repo commit
65+
repo="$1"
66+
commit="$2"
67+
echo "https://$repo/archive/$commit.tar.gz"
68+
}
69+
70+
dl_and_extract() {
71+
# TODO(ahmetb) remove this function. no longer dl'ing tarballs since they
72+
# won't have a .git dir to infer the commit ID from to be used by refdocs.
73+
local url dest
74+
url="$1"
75+
dest="$2"
76+
mkdir -p "${dest}"
77+
curl -sSLf "$url" | tar zxf - --directory="$dest" --strip 1
78+
}
79+
80+
clone_at_commit() {
81+
local repo commit dest
82+
repo="$1"
83+
commit="$2"
84+
dest="$3"
85+
mkdir -p "${dest}"
86+
git clone "${repo}" "${dest}"
87+
git --git-dir="${dest}/.git" --work-tree="${dest}" checkout --detach --quiet "${commit}"
88+
}
89+
90+
gen_refdocs() {
91+
local refdocs_bin gopath out_file repo_root
92+
refdocs_bin="$1"
93+
gopath="$2"
94+
out_file="$3"
95+
repo_root="$4"
96+
97+
(
98+
cd "${repo_root}"
99+
env GOPATH="${gopath}" "${refdocs_bin}" \
100+
-out-file "${gopath}/out/${out_file}" \
101+
-api-dir "./pkg/apis" \
102+
-config "${SCRIPTDIR}/reference-docs-gen-config.json"
103+
)
104+
}
105+
106+
107+
main() {
108+
if [[ -n "${GOPATH:-}" ]]; then
109+
fail "GOPATH should not be set."
110+
fi
111+
if ! command -v "go" 1>/dev/null ; then
112+
fail "\"go\" is not in PATH"
113+
fi
114+
if ! command -v "git" 1>/dev/null ; then
115+
fail "\"git\" is not in PATH"
116+
fi
117+
118+
# install and place the refdocs tool
119+
local refdocs_bin refdocs_bin_expected refdocs_dir
120+
refdocs_dir="$(mktemp -d)"
121+
refdocs_bin="${refdocs_dir}/refdocs"
122+
# clone repo for ./templates
123+
git clone --quiet --depth=1 "${REFDOCS_REPO}" "${refdocs_dir}"
124+
# install bin
125+
install_go_bin "${REFDOCS_PKG}@${REFDOCS_VER}"
126+
# move bin to final location
127+
refdocs_bin_expected="$(go env GOPATH)/bin/$(basename ${REFDOCS_PKG})"
128+
mv "${refdocs_bin_expected}" "${refdocs_bin}"
129+
[[ ! -f "${refdocs_bin}" ]] && fail "refdocs failed to install"
130+
131+
local clone_root
132+
clone_root="$(mktemp -d)"
133+
134+
local knative_serving_root
135+
knative_serving_root="${clone_root}/src/${KNATIVE_SERVING_REPO}"
136+
clone_at_commit "https://${KNATIVE_SERVING_REPO}.git" "${KNATIVE_SERVING_COMMIT}" \
137+
"${knative_serving_root}"
138+
gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_SERVING_OUT_FILE}" \
139+
"${knative_serving_root}"
140+
141+
local knative_build_root
142+
knative_build_root="${clone_root}/src/${KNATIVE_BUILD_REPO}"
143+
clone_at_commit "https://${KNATIVE_BUILD_REPO}.git" "${KNATIVE_BUILD_COMMIT}" \
144+
"${knative_build_root}"
145+
gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_BUILD_OUT_FILE}" \
146+
"${knative_build_root}"
147+
148+
local knative_eventing_root
149+
knative_eventing_root="${clone_root}/src/${KNATIVE_EVENTING_REPO}"
150+
clone_at_commit "https://${KNATIVE_EVENTING_REPO}.git" "${KNATIVE_EVENTING_COMMIT}" \
151+
"${knative_eventing_root}"
152+
gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_EVENTING_OUT_FILE}" \
153+
"${knative_eventing_root}"
154+
155+
local knative_eventing_sources_root
156+
knative_eventing_sources_root="${clone_root}/src/${KNATIVE_EVENTING_SOURCES_REPO}"
157+
clone_at_commit "https://${KNATIVE_EVENTING_SOURCES_REPO}.git" "${KNATIVE_EVENTING_SOURCES_COMMIT}" \
158+
"${knative_eventing_sources_root}"
159+
gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_EVENTING_SOURCES_OUT_FILE}" \
160+
"${knative_eventing_sources_root}"
161+
162+
log "Generated files written to ${clone_root}/out/."
163+
log "Copy the files in reference/ directory to knative/docs."
164+
if command -v open >/dev/null; then
165+
open "${clone_root}/out/"
166+
fi
167+
}
168+
169+
main "$@"

‎hack/reference-docs-gen-config.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"hideMemberFields": [
3+
"TypeMeta"
4+
],
5+
"hideTypePatterns": [
6+
"ParseError$",
7+
"List$"
8+
],
9+
"externalPackages": [
10+
{
11+
"typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
12+
"docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
13+
},
14+
{
15+
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/",
16+
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
17+
},
18+
{
19+
"typeMatchPrefix": "^github\\.com/knative/pkg/apis/duck/",
20+
"docsURLTemplate": "https://godoc.org/github.com/knative/pkg/apis/duck/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}"
21+
}
22+
],
23+
"typeDisplayNamePrefixOverrides": {
24+
"k8s.io/api/": "Kubernetes ",
25+
"k8s.io/apimachinery/pkg/apis/": "Kubernetes "
26+
},
27+
"markdownDisabled": false
28+
}

‎reference/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Knative API Reference documentation
2+
3+
- [Serving API](serving.md)
4+
- [Build API](build.md)
5+
- [Eventing API](eventing/eventing.md)
6+
- [Event Sources API](eventing/eventing-sources.md)

0 commit comments

Comments
 (0)