Skip to content

Commit 88fbc86

Browse files
abayertekton-robot
abayer
authored and
tekton-robot
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, forked to https://github.com/tektoncd/ahmetb-gen-crd-api-reference-docs, 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 afb2833 commit 88fbc86

39 files changed

+19540
-11
lines changed

‎docs/pipeline-api.md‎

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

‎go.mod‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ module github.com/tektoncd/pipeline
33
go 1.17
44

55
require (
6+
github.com/ahmetb/gen-crd-api-reference-docs v0.3.1-0.20220720053627-e327d0730470 // Waiting for https://github.com/ahmetb/gen-crd-api-reference-docs/pull/43/files to merge
67
github.com/cloudevents/sdk-go/v2 v2.10.1
78
github.com/containerd/containerd v1.5.13
89
github.com/google/go-cmp v0.5.8
@@ -16,7 +17,7 @@ require (
1617
github.com/mitchellh/go-homedir v1.1.0
1718
github.com/opencontainers/image-spec v1.0.3-0.20220114050600-8b9d41f48198
1819
github.com/pkg/errors v0.9.1
19-
github.com/tektoncd/plumbing v0.0.0-20220329085922-d765a5cba75f
20+
github.com/tektoncd/plumbing v0.0.0-20220728121531-8a725746af4f
2021
go.opencensus.io v0.23.0
2122
go.uber.org/zap v1.21.0
2223
golang.org/x/oauth2 v0.0.0-20220223155221-ee480838109b
@@ -113,6 +114,7 @@ require (
113114
github.com/prometheus/common v0.32.1 // indirect
114115
github.com/prometheus/procfs v0.6.0 // indirect
115116
github.com/prometheus/statsd_exporter v0.21.0 // indirect
117+
github.com/russross/blackfriday/v2 v2.1.0 // indirect
116118
github.com/shurcooL/githubv4 v0.0.0-20190718010115-4ba037080260 // indirect
117119
github.com/shurcooL/graphql v0.0.0-20181231061246-d48a9a75455f // indirect
118120
github.com/sirupsen/logrus v1.8.1 // indirect
@@ -149,3 +151,5 @@ require (
149151
sigs.k8s.io/json v0.0.0-20211208200746-9f7c6b3444d2 // indirect
150152
sigs.k8s.io/structured-merge-diff/v4 v4.2.1 // indirect
151153
)
154+
155+
replace github.com/ahmetb/gen-crd-api-reference-docs => github.com/tektoncd/ahmetb-gen-crd-api-reference-docs v0.3.1-0.20220729140133-6ce2d5aafcb4 // Waiting for https://github.com/ahmetb/gen-crd-api-reference-docs/pull/43/files to merge

‎go.sum‎

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

‎hack/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,7 @@ Tekton Pipelines.
99
- [`update-openapigen.sh`](./update-openapigen.sh): Updates OpenAPI specification and Swagger file.
1010
- [`verify-codegen.sh`](./verify-codegen.sh): Verifies that auto-generated
1111
client libraries are up-to-date.
12+
- [`update-reference-docs.sh`](./update-reference-docs.sh) and related files: Generates [`docs/pipeline-api.md`](../docs/pipeline-api.md).
13+
- [`reference-docs-gen-config.json`](./reference-docs-gen-config.json) is the configuration file for the [`gen-api-reference-docs`](https://github.com/tektoncd/ahmetb-gen-crd-api-reference-docs) binary.
14+
- [`reference-docs-template`](./reference-docs-template) contains Go templates for the generated Markdown.
1215
- Release docs have been moved to [the top-level `tekton` dir](../tekton)

‎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.23/#{{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/tools.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,6 @@ import (
1616
_ "k8s.io/kube-openapi/cmd/openapi-gen"
1717

1818
_ "knative.dev/pkg/codegen/cmd/injection-gen"
19+
20+
_ "github.com/ahmetb/gen-crd-api-reference-docs"
1921
)

0 commit comments

Comments
 (0)