Skip to content

Commit 7272f70

Browse files
abayerabayer
committed
Generate API reference docs for Pipeline
This is the first part of addressing #1250 (and tektoncd/website#117). Using https://github.com/ahmetb/gen-crd-api-reference-docs/, the tool Knative uses for this, plus my PR at ahmetb/gen-crd-api-reference-docs#43 for an issue with `pkg/apis/pipeline/pod`, this adds generation of `docs/pipeline-api.md` to `hack/update-codegen.sh`. Signed-off-by: Andrew Bayer <andrew.bayer@gmail.com>
1 parent e0e994e commit 7272f70

13 files changed

Lines changed: 8852 additions & 2 deletions

File tree

‎docs/pipeline-api.md‎

Lines changed: 8550 additions & 0 deletions
Large diffs are not rendered by default.

‎go.mod‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ module github.com/tektoncd/pipeline
33
go 1.13
44

55
require (
6+
github.com/abayer/gen-crd-api-reference-docs v0.999.0 // indirect
67
github.com/cloudevents/sdk-go/v2 v2.5.0
78
github.com/containerd/containerd v1.5.2
89
github.com/docker/cli v20.10.8+incompatible // indirect

‎go.sum‎

Lines changed: 6 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
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.21/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
17+
},
18+
{
19+
"typeMatchPrefix": "^knative\\.dev/pkg/apis/duck",
20+
"docsURLTemplate": "https://pkg.go.dev/knative.dev/pkg/apis/duck/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}"
21+
},
22+
{
23+
"typeMatchPrefix": "^knative\\.dev/pkg/apis\\.URL$",
24+
"docsURLTemplate": "https://pkg.go.dev/knative.dev/pkg/apis#URL"
25+
},
26+
{
27+
"typeMatchPrefix": "^knative\\.dev/networking/pkg/apis/networking",
28+
"docsURLTemplate": "https://pkg.go.dev/knative.dev/networking/pkg/apis/networking#{{.TypeIdentifier}}"
29+
},
30+
{
31+
"typeMatchPrefix": "^time\\.Duration$",
32+
"docsURLTemplate": "https://golang.org/pkg/time/#Duration"
33+
}
34+
],
35+
"typeDisplayNamePrefixOverrides": {
36+
"k8s.io/api/": "Kubernetes ",
37+
"k8s.io/apimachinery/pkg/apis/": "Kubernetes "
38+
},
39+
"markdownDisabled": false,
40+
"gitCommitDisabled": true
41+
}
42+

‎hack/reference-docs-template/members.tpl‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{{ define "members" }}
2+
3+
{{ range .Members }}
4+
{{ if not (hiddenMember .)}}
5+
<tr>
6+
<td>
7+
<code>{{ fieldName . }}</code><br/>
8+
<em>
9+
{{ if linkForType .Type }}
10+
<a href="{{ linkForType .Type}}">
11+
{{ typeDisplayName .Type }}
12+
</a>
13+
{{ else }}
14+
{{ typeDisplayName .Type }}
15+
{{ end }}
16+
</em>
17+
</td>
18+
<td>
19+
{{ if fieldEmbedded . }}
20+
<p>
21+
(Members of <code>{{ fieldName . }}</code> are embedded into this type.)
22+
</p>
23+
{{ end}}
24+
25+
{{ if isOptionalMember .}}
26+
<em>(Optional)</em>
27+
{{ end }}
28+
29+
{{ safe (renderComments .CommentLines) }}
30+
31+
{{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
32+
Refer to the Kubernetes API documentation for the fields of the
33+
<code>metadata</code> field.
34+
{{ end }}
35+
36+
{{ if or (eq (fieldName .) "spec") }}
37+
<br/>
38+
<br/>
39+
<table>
40+
{{ template "members" .Type }}
41+
</table>
42+
{{ end }}
43+
</td>
44+
</tr>
45+
{{ end }}
46+
{{ end }}
47+
48+
{{ end }}

‎hack/reference-docs-template/pkg.tpl‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{{ define "packages" }}
2+
3+
{{ with .packages}}
4+
<p>Packages:</p>
5+
<ul>
6+
{{ range . }}
7+
<li>
8+
<a href="#{{- packageAnchorID . -}}">{{ packageDisplayName . }}</a>
9+
</li>
10+
{{ end }}
11+
</ul>
12+
{{ end}}
13+
14+
{{ range .packages }}
15+
<h2 id="{{- packageAnchorID . -}}">
16+
{{- packageDisplayName . -}}
17+
</h2>
18+
19+
{{ with (index .GoPackages 0 )}}
20+
{{ with .DocComments }}
21+
<div>
22+
{{ safe (renderComments .) }}
23+
</div>
24+
{{ end }}
25+
{{ end }}
26+
27+
Resource Types:
28+
<ul>
29+
{{- range (visibleTypes (sortedTypes .Types)) -}}
30+
{{ if isExportedType . -}}
31+
<li>
32+
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
33+
</li>
34+
{{- end }}
35+
{{- end -}}
36+
</ul>
37+
38+
{{ range (visibleTypes (sortedTypes .Types))}}
39+
{{ template "type" . }}
40+
{{ end }}
41+
<hr/>
42+
{{ end }}
43+
44+
<p><em>
45+
Generated with <code>gen-crd-api-reference-docs</code>
46+
{{ with .gitCommit }} on git commit <code>{{ . }}</code>{{end}}.
47+
</em></p>
48+
49+
{{ end }}

‎hack/reference-docs-template/placeholder.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
// Placeholder file to make Go vendor this directory properly.
2+
package template

‎hack/reference-docs-template/type.tpl‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
{{ define "type" }}
2+
3+
<h3 id="{{ anchorIDForType . }}">
4+
{{- .Name.Name }}
5+
{{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias){{ end -}}
6+
</h3>
7+
{{ with (typeReferences .) }}
8+
<p>
9+
(<em>Appears on:</em>
10+
{{- $prev := "" -}}
11+
{{- range . -}}
12+
{{- if $prev -}}, {{ end -}}
13+
{{- $prev = . -}}
14+
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
15+
{{- end -}}
16+
)
17+
</p>
18+
{{ end }}
19+
20+
<div>
21+
{{ safe (renderComments .CommentLines) }}
22+
</div>
23+
24+
{{ with (constantsOfType .) }}
25+
<table>
26+
<thead>
27+
<tr>
28+
<th>Value</th>
29+
<th>Description</th>
30+
</tr>
31+
</thead>
32+
<tbody>
33+
{{- range . -}}
34+
<tr>
35+
{{- /*
36+
renderComments implicitly creates a <p> element, so we
37+
add one to the display name as well to make the contents
38+
of the two cells align evenly.
39+
*/ -}}
40+
<td><p>{{ typeDisplayName . }}</p></td>
41+
<td>{{ safe (renderComments .CommentLines) }}</td>
42+
</tr>
43+
{{- end -}}
44+
</tbody>
45+
</table>
46+
{{ end }}
47+
48+
{{ if .Members }}
49+
<table>
50+
<thead>
51+
<tr>
52+
<th>Field</th>
53+
<th>Description</th>
54+
</tr>
55+
</thead>
56+
<tbody>
57+
{{ if isExportedType . }}
58+
<tr>
59+
<td>
60+
<code>apiVersion</code><br/>
61+
string</td>
62+
<td>
63+
<code>
64+
{{apiGroup .}}
65+
</code>
66+
</td>
67+
</tr>
68+
<tr>
69+
<td>
70+
<code>kind</code><br/>
71+
string
72+
</td>
73+
<td><code>{{.Name.Name}}</code></td>
74+
</tr>
75+
{{ end }}
76+
{{ template "members" .}}
77+
</tbody>
78+
</table>
79+
{{ end }}
80+
81+
{{ end }}

‎hack/update-codegen.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,6 @@ ${REPO_ROOT_DIR}/hack/update-deps.sh
8282

8383
# Make sure the OpenAPI specification and Swagger file are up-to-date
8484
${REPO_ROOT_DIR}/hack/update-openapigen.sh
85+
86+
# Make sure the generated API reference docs are up-to-date
87+
${REPO_ROOT_DIR}/hack/update-reference-docs.sh

‎hack/update-reference-docs.sh‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
#!/usr/bin/env bash
2+
3+
# Copyright 2020 The Tekton Authors
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
set -o errexit
18+
set -o nounset
19+
20+
echo "Generating API reference docs ..."
21+
# TODO(abayer): Switch to github.com/ahmetb/gen-crd-api-reference-docs when https://github.com/ahmetb/gen-crd-api-reference-docs/pull/43 is merged
22+
go run -mod=readonly github.com/abayer/gen-crd-api-reference-docs \
23+
-config "./hack/reference-docs-gen-config.json" \
24+
-api-dir "github.com/tektoncd/pipeline/pkg/apis" \
25+
-template-dir "./hack/reference-docs-template" \
26+
-out-file "./docs/pipeline-api.md"

0 commit comments

Comments
 (0)