forked from tektoncd/pipeline
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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, 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]>
- Loading branch information
Showing
39 changed files
with
19,540 additions
and
11 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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.23/#{{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 | ||
| } | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| // Placeholder file to make Go vendor this directory properly. | ||
| package template |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 ..." | ||
| go run github.com/ahmetb/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" | ||
| sed -i '1s/^/<!--\n---\ntitle: Pipeline API\nlinkTitle: Pipeline API\nweight: 1000\n---\n-->\n\n/' ./docs/pipeline-api.md |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
Oops, something went wrong.