Skip to content

Commit c7de3c0

Browse files
abayerabayer
committed
Generate API reference docs for Pipeline
This is the first part of addressing tektoncd#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 <[email protected]>
1 parent 5495edd commit c7de3c0

35 files changed

+18262
-3
lines changed

‎docs/pipeline-api.md

+8,550
Large diffs are not rendered by default.

‎go.mod

+3-1
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,15 @@ module github.com/tektoncd/pipeline
33
go 1.17
44

55
require (
6+
github.com/abayer/gen-crd-api-reference-docs v0.999.0
67
github.com/cloudevents/sdk-go/v2 v2.5.0
78
github.com/containerd/containerd v1.5.10
89
github.com/ghodss/yaml v1.0.0
910
github.com/google/go-cmp v0.5.7
1011
github.com/google/go-containerregistry v0.8.1-0.20220216220642-00c59d91847c
1112
github.com/google/go-containerregistry/pkg/authn/k8schain v0.0.0-20220216220642-00c59d91847c
1213
github.com/google/uuid v1.3.0
14+
github.com/hashicorp/errwrap v1.0.0
1315
github.com/hashicorp/go-multierror v1.1.1
1416
github.com/hashicorp/golang-lru v0.5.4
1517
github.com/jenkins-x/go-scm v1.10.10
@@ -90,7 +92,6 @@ require (
9092
github.com/google/gofuzz v1.2.0 // indirect
9193
github.com/googleapis/gnostic v0.5.5 // indirect
9294
github.com/grpc-ecosystem/grpc-gateway v1.16.0 // indirect
93-
github.com/hashicorp/errwrap v1.0.0 // indirect
9495
github.com/imdario/mergo v0.3.12 // indirect
9596
github.com/jmespath/go-jmespath v0.4.0 // indirect
9697
github.com/josharian/intern v1.0.0 // indirect
@@ -111,6 +112,7 @@ require (
111112
github.com/prometheus/common v0.32.1 // indirect
112113
github.com/prometheus/procfs v0.6.0 // indirect
113114
github.com/prometheus/statsd_exporter v0.21.0 // indirect
115+
github.com/russross/blackfriday/v2 v2.1.0 // indirect
114116
github.com/shurcooL/githubv4 v0.0.0-20190718010115-4ba037080260 // indirect
115117
github.com/shurcooL/graphql v0.0.0-20181231061246-d48a9a75455f // indirect
116118
github.com/sirupsen/logrus v1.8.1 // indirect

‎go.sum

+6
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

+42
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

+48
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

+49
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

+2
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

+81
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/tools.go

+3
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,7 @@ import (
1616
_ "k8s.io/kube-openapi/cmd/openapi-gen"
1717

1818
_ "knative.dev/pkg/codegen/cmd/injection-gen"
19+
20+
// TODO(abayer): Switch to github.com/ahmetb/gen-crd-api-reference-docs once https://github.com/ahmetb/gen-crd-api-reference-docs/pull/43 is merged/released
21+
_ "github.com/abayer/gen-crd-api-reference-docs"
1922
)

‎hack/update-codegen.sh

+3
Original file line numberDiff line numberDiff line change
@@ -86,3 +86,6 @@ ${REPO_ROOT_DIR}/hack/update-deps.sh
8686

8787
# Make sure the OpenAPI specification and Swagger file are up-to-date
8888
${REPO_ROOT_DIR}/hack/update-openapigen.sh
89+
90+
# Make sure the generated API reference docs are up-to-date
91+
${REPO_ROOT_DIR}/hack/update-reference-docs.sh

‎hack/update-reference-docs.sh

+26
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/vendor is updated
22+
go run 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"

‎pkg/apis/doc.go

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/*
2+
Copyright 2019 The Tekton Authors
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Package apis contains API Schema definitions for the various API groups
18+
package apis

‎pkg/apis/pipeline/pod/doc.go

+3-2
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ See the License for the specific language governing permissions and
1414
limitations under the License.
1515
*/
1616

17-
// +k8s:openapi-gen=true
18-
1917
// Package pod contains non-versioned pod configuration
18+
// +k8s:openapi-gen=true
19+
// +gencrdrefdocs:unversionedTypes
20+
// +groupName=tekton.dev
2021
package pod

‎pkg/apis/run/v1alpha1/doc.go

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
/*
2+
Copyright 2019 The Tekton Authors
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Package v1alpha1 contains API Schema definitions for the run v1alpha1 API group
18+
// +groupName=tekton.dev
19+
package v1alpha1

‎vendor/github.com/abayer/gen-crd-api-reference-docs/.gitignore

+16
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)