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

@@ -3,6 +3,7 @@ module github.com/tektoncd/pipeline
 go 1.16
 
 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.2
  github.com/docker/cli v20.10.8+incompatible // indirect

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