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 <andrew.bayer@gmail.com>

go.mod

@@ -10,6 +10,7 @@ replace (
 )
 
 require (
+	github.com/abayer/gen-crd-api-reference-docs v0.999.0
 	github.com/cloudevents/sdk-go/v2 v2.5.0
 	github.com/containerd/containerd v1.5.10
 	github.com/ghodss/yaml v1.0.0

hack/reference-docs-gen-config.json

@@ -0,0 +1,42 @@
+{
+    "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.21/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
+        },
+        {
+            "typeMatchPrefix": "^knative\\.dev/pkg/apis/duck",
+            "docsURLTemplate": "https://pkg.go.dev/knative.dev/pkg/apis/duck/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}"
+        },
+        {
+            "typeMatchPrefix": "^knative\\.dev/pkg/apis\\.URL$",
+            "docsURLTemplate": "https://pkg.go.dev/knative.dev/pkg/apis#URL"
+        },
+        {
+            "typeMatchPrefix": "^knative\\.dev/networking/pkg/apis/networking",
+            "docsURLTemplate": "https://pkg.go.dev/knative.dev/networking/pkg/apis/networking#{{.TypeIdentifier}}"
+        },
+        {
+            "typeMatchPrefix": "^time\\.Duration$",
+            "docsURLTemplate": "https://golang.org/pkg/time/#Duration"
+        }
+    ],
+    "typeDisplayNamePrefixOverrides": {
+        "k8s.io/api/": "Kubernetes ",
+        "k8s.io/apimachinery/pkg/apis/": "Kubernetes "
+    },
+    "markdownDisabled": false,
+    "gitCommitDisabled": true
+}
+

hack/reference-docs-template/members.tpl

@@ -0,0 +1,48 @@
+{{ define "members" }}
+
+{{ range .Members }}
+{{ if not (hiddenMember .)}}
+<tr>
+    <td>
+        <code>{{ fieldName . }}</code><br/>
+        <em>
+            {{ if linkForType .Type }}
+                <a href="{{ linkForType .Type}}">
+                    {{ typeDisplayName .Type }}
+                </a>
+            {{ else }}
+                {{ typeDisplayName .Type }}
+            {{ end }}
+        </em>
+    </td>
+    <td>
+        {{ if fieldEmbedded . }}
+            <p>
+                (Members of <code>{{ fieldName . }}</code> are embedded into this type.)
+            </p>
+        {{ end}}
+
+        {{ if isOptionalMember .}}
+            <em>(Optional)</em>
+        {{ end }}
+
+        {{ safe (renderComments .CommentLines) }}
+
+    {{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
+        Refer to the Kubernetes API documentation for the fields of the
+        <code>metadata</code> field.
+    {{ end }}
+
+    {{ if or (eq (fieldName .) "spec") }}
+        <br/>
+        <br/>
+        <table>
+            {{ template "members" .Type }}
+        </table>
+    {{ end }}
+    </td>
+</tr>
+{{ end }}
+{{ end }}
+
+{{ end }}

hack/reference-docs-template/pkg.tpl

@@ -0,0 +1,49 @@
+{{ define "packages" }}
+
+{{ with .packages}}
+<p>Packages:</p>
+<ul>
+    {{ range . }}
+    <li>
+        <a href="#{{- packageAnchorID . -}}">{{ packageDisplayName . }}</a>
+    </li>
+    {{ end }}
+</ul>
+{{ end}}
+
+{{ range .packages }}
+    <h2 id="{{- packageAnchorID . -}}">
+        {{- packageDisplayName . -}}
+    </h2>
+
+    {{ with (index .GoPackages 0 )}}
+        {{ with .DocComments }}
+        <div>
+            {{ safe (renderComments .) }}
+        </div>
+        {{ end }}
+    {{ end }}
+
+    Resource Types:
+    <ul>
+    {{- range (visibleTypes (sortedTypes .Types)) -}}
+        {{ if isExportedType . -}}
+        <li>
+            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
+        </li>
+        {{- end }}
+    {{- end -}}
+    </ul>
+
+    {{ range (visibleTypes (sortedTypes .Types))}}
+        {{ template "type" .  }}
+    {{ end }}
+    <hr/>
+{{ end }}
+
+<p><em>
+    Generated with <code>gen-crd-api-reference-docs</code>
+    {{ with .gitCommit }} on git commit <code>{{ . }}</code>{{end}}.
+</em></p>
+
+{{ end }}

hack/reference-docs-template/placeholder.go

@@ -0,0 +1,2 @@
+// Placeholder file to make Go vendor this directory properly.
+package template

hack/reference-docs-template/type.tpl

@@ -0,0 +1,81 @@
+{{ define "type" }}
+
+<h3 id="{{ anchorIDForType . }}">
+    {{- .Name.Name }}
+    {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias){{ end -}}
+</h3>
+{{ with (typeReferences .) }}
+    <p>
+        (<em>Appears on:</em>
+        {{- $prev := "" -}}
+        {{- range . -}}
+            {{- if $prev -}}, {{ end -}}
+            {{- $prev = . -}}
+            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
+        {{- end -}}
+        )
+    </p>
+{{ end }}
+
+<div>
+    {{ safe (renderComments .CommentLines) }}
+</div>
+
+{{ with (constantsOfType .) }}
+<table>
+    <thead>
+        <tr>
+            <th>Value</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+      {{- range . -}}
+      <tr>
+        {{- /*
+            renderComments implicitly creates a <p> element, so we
+            add one to the display name as well to make the contents
+            of the two cells align evenly.
+        */ -}}
+        <td><p>{{ typeDisplayName . }}</p></td>
+        <td>{{ safe (renderComments .CommentLines) }}</td>
+      </tr>
+      {{- end -}}
+    </tbody>
+</table>
+{{ end }}
+
+{{ if .Members }}
+<table>
+    <thead>
+        <tr>
+            <th>Field</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        {{ if isExportedType . }}
+        <tr>
+            <td>
+                <code>apiVersion</code><br/>
+                string</td>
+            <td>
+                <code>
+                    {{apiGroup .}}
+                </code>
+            </td>
+        </tr>
+        <tr>
+            <td>
+                <code>kind</code><br/>
+                string
+            </td>
+            <td><code>{{.Name.Name}}</code></td>
+        </tr>
+        {{ end }}
+        {{ template "members" .}}
+    </tbody>
+</table>
+{{ end }}
+
+{{ end }}

hack/tools.go

@@ -15,4 +15,7 @@ import (
 	_ "k8s.io/kube-openapi/cmd/openapi-gen"
 
 	_ "knative.dev/pkg/codegen/cmd/injection-gen"
+
+	// 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
+	_ "github.com/abayer/gen-crd-api-reference-docs"
 )

hack/update-codegen.sh

@@ -86,3 +86,6 @@ ${REPO_ROOT_DIR}/hack/update-deps.sh
 
 # Make sure the OpenAPI specification and Swagger file are up-to-date
 ${REPO_ROOT_DIR}/hack/update-openapigen.sh
+
+# Make sure the generated API reference docs are up-to-date
+${REPO_ROOT_DIR}/hack/update-reference-docs.sh

hack/update-reference-docs.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# Copyright 2020 The Tekton 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 -o errexit
+set -o nounset
+
+echo "Generating API reference docs ..."
+# 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
+go run github.com/abayer/gen-crd-api-reference-docs \
+    -config "./hack/reference-docs-gen-config.json" \
+    -api-dir "github.com/tektoncd/pipeline/pkg/apis" \
+    -template-dir "./hack/reference-docs-template" \
+    -out-file "./docs/pipeline-api.md"

pkg/apis/doc.go

@@ -0,0 +1,18 @@
+/*
+Copyright 2019 The Tekton 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.
+*/
+
+// Package apis contains API Schema definitions for the various API groups
+package apis

pkg/apis/pipeline/pod/doc.go

@@ -14,7 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// +k8s:openapi-gen=true
-
 // Package pod contains non-versioned pod configuration
+// +k8s:openapi-gen=true
+// +gencrdrefdocs:unversionedTypes
+// +groupName=tekton.dev
 package pod

pkg/apis/run/v1alpha1/doc.go

@@ -0,0 +1,19 @@
+/*
+Copyright 2019 The Tekton 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.
+*/
+
+// Package v1alpha1 contains API Schema definitions for the run v1alpha1 API group
+// +groupName=tekton.dev
+package v1alpha1