Generate API reference docs for Pipeline #4494

abayer · 2022-01-18T17:17:45Z

Changes

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 for an issue with pkg/apis/pipeline/pod, this adds generation of docs/pipeline-api.md to hack/update-codegen.sh.

I assume there'll need to be a follow up PR to the website tooling to actually do something with this new file!

/kind documentation

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

Docs included if any changes are user facing
Tests included if any functionality added or changed
Follows the commit message standard
Meets the Tekton contributor standards (including
functionality, content, code)
Release notes block below has been filled in or deleted (only if no user facing changes)

Release Notes

NONE

abayer · 2022-01-18T17:20:01Z

/assign @skaegi
/assign @vdemeester

abayer · 2022-01-18T18:09:41Z

I've had to hack things around with go.mod - I can't seem to get go mod vendor to work. I keep getting:

github.com/tektoncd/pipeline/cmd/controller imports
	k8s.io/client-go/rest imports
	k8s.io/client-go/plugin/pkg/client/auth/exec imports
	io/fs: malformed module path "io/fs": missing dot in first path element

So I've hardcoded go run -mod=readonly in hack/update-reference-docs.sh. Hopefully that works in CI - it works for me locally, but so did a bunch of other things that failed on CI.

EDIT: Ok, jumped through some hoops (bumping Go to 1.15 mainly) and got it to vendor. Now I need to fix something else.

abayer · 2022-01-18T21:05:54Z

/retest

abayer · 2022-01-18T21:08:10Z

/assign @lbernick
/assign @jerop

FYI, this is knocking off another v1 TODO. =)

tekton-robot · 2022-01-18T21:08:12Z

@abayer: GitHub didn't allow me to assign the following users: lbernick.

Note that only tektoncd members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

/assign @lbernick
/assign @jerop

FYI, this is knocking off another v1 TODO. =)

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

lbernick · 2022-01-24T15:38:25Z

pkg/apis/doc.go

+*/
+
+// Package apis contains API Schema definitions for the various API groups
+package apis


Does this need an annotation similar to those in pod/doc.go and run/v1alpha1/doc.go?

It doesn't strictly need one, but we could add +k8s:deepcopy-gen=package like in https://github.com/knative/serving/blob/main/pkg/apis/doc.go#L17. I don't think it would actually do anything, though.

lbernick · 2022-01-24T15:39:38Z

Awesome, thank you Andrew!

Do you need to also add the annotations to the other CRDs? (e.g. here for Pipeline and similarly for PipelineRun, Task, TaskRun, etc)

abayer · 2022-01-24T15:54:25Z

@lbernick No - pkg/apis/pipeline/pod is a special case, since it's used by pkg/apis/pipeline/v1alpha1 and pkg/apis/pipeline/v1beta1 but is itself unversioned.

lbernick · 2022-01-24T16:27:13Z

LGTM!

afrittoli · 2022-02-16T11:11:36Z

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


Could you comment here with a link to your PR https://github.com/ahmetb/gen-crd-api-reference-docs/pull/43/files so we don't forget to switch back once it's merged?

Good point! On it.

abayer · 2022-03-25T13:15:58Z

/retest

tekton-robot · 2022-07-02T12:52:02Z

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale with a justification.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle stale

Send feedback to tektoncd/plumbing.

tekton-robot · 2022-08-01T13:12:55Z

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten with a justification.
Rotten issues close after an additional 30d of inactivity.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle rotten

Send feedback to tektoncd/plumbing.

abayer · 2022-08-01T13:24:42Z

/remove-lifecycle rotten

I'm actually working on resurrecting this today. =)

tekton-robot · 2022-08-01T14:38:28Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: vdemeester

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [vdemeester]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

abayer · 2022-08-01T14:38:46Z

/cc @afrittoli @lbernick - I think this should work/be ready now, using https://github.com/tektoncd/ahmetb-gen-crd-api-reference-docs.

abayer · 2022-08-01T14:43:38Z

/retest

lbernick · 2022-08-01T14:43:05Z

go.mod

@@ -149,3 +151,5 @@ require (
 	sigs.k8s.io/json v0.0.0-20211208200746-9f7c6b3444d2 // indirect
 	sigs.k8s.io/structured-merge-diff/v4 v4.2.1 // indirect
 )
+
+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


Is the comment here still relevant? do you need the replace?

Yes, because the package in the forked repo is still github.com/ahmetb/gen-crd-api-reference-docs.

lbernick · 2022-08-01T14:43:52Z

hack/update-reference-docs.sh

+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


this comment can be removed

Good catch, I forgot that.

lbernick · 2022-08-01T14:44:56Z

hack/reference-docs-gen-config.json

@@ -0,0 +1,42 @@
+{


would you mind adding a readme in /hack that explains a bit what these files you're adding are for, and link to any reference docs?

Lemme see what I can remember. =)

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

abayer · 2022-08-01T15:42:54Z

hack/README.md

@@ -9,4 +9,7 @@ Tekton Pipelines.
 - [`update-openapigen.sh`](./update-openapigen.sh): Updates OpenAPI specification and Swagger file.
 - [`verify-codegen.sh`](./verify-codegen.sh): Verifies that auto-generated
  client libraries are up-to-date.
+- [`update-reference-docs.sh`](./update-reference-docs.sh) and related files: Generates [`docs/pipeline-api.md`](../docs/pipeline-api.md).
+  - [`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.
+  - [`reference-docs-template`](./reference-docs-template) contains Go templates for the generated Markdown.


@lbernick Is this (and above) what you were looking for?

sure yeah this works!

lbernick

/lgtm

lbernick · 2022-08-01T16:18:28Z

hack/README.md

@@ -9,4 +9,7 @@ Tekton Pipelines.
 - [`update-openapigen.sh`](./update-openapigen.sh): Updates OpenAPI specification and Swagger file.
 - [`verify-codegen.sh`](./verify-codegen.sh): Verifies that auto-generated
  client libraries are up-to-date.
+- [`update-reference-docs.sh`](./update-reference-docs.sh) and related files: Generates [`docs/pipeline-api.md`](../docs/pipeline-api.md).
+  - [`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.
+  - [`reference-docs-template`](./reference-docs-template) contains Go templates for the generated Markdown.


sure yeah this works!

tekton-robot added release-note-none Denotes a PR that doesnt merit a release note. kind/documentation Categorizes issue or PR as related to documentation. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Jan 18, 2022

tekton-robot requested review from dibyom and dlorenc January 18, 2022 17:17

tekton-robot assigned skaegi and vdemeester Jan 18, 2022

abayer force-pushed the api-reference-docs branch 3 times, most recently from dda844a to 7272f70 Compare January 18, 2022 18:08

abayer force-pushed the api-reference-docs branch 2 times, most recently from 20f994f to c7e43f4 Compare January 18, 2022 18:44

tekton-robot assigned jerop Jan 18, 2022

abayer force-pushed the api-reference-docs branch 2 times, most recently from 31b1a7c to 81ed625 Compare January 19, 2022 17:30

abayer mentioned this pull request Jan 20, 2022

Add OpenAPI generation and swagger to update-codegen.sh tektoncd/triggers#1297

Merged

4 tasks

tekton-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jan 22, 2022

nikhil-thomas mentioned this pull request Jan 23, 2022

Generate Tektoncd/Operator API Reference (for website) tektoncd/operator#586

Closed

lbernick reviewed Jan 24, 2022

View reviewed changes

abayer force-pushed the api-reference-docs branch from 81ed625 to a29a3a3 Compare January 24, 2022 15:58

tekton-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jan 24, 2022

afrittoli reviewed Feb 16, 2022

View reviewed changes

abayer force-pushed the api-reference-docs branch from f079b5c to c9a8b74 Compare March 25, 2022 12:36

abayer force-pushed the api-reference-docs branch from c9a8b74 to 1161a56 Compare March 29, 2022 16:29

tekton-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 31, 2022

abayer force-pushed the api-reference-docs branch from 1161a56 to b820618 Compare March 31, 2022 16:46

tekton-robot added needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. and removed needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. labels Mar 31, 2022

abayer mentioned this pull request Apr 4, 2022

Please fork https://github.com/ahmetb/gen-crd-api-reference-docs into the tektoncd org tektoncd/community#668

Closed

tekton-robot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Jul 2, 2022

tekton-robot added lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. and removed lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. labels Aug 1, 2022

tekton-robot removed the lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. label Aug 1, 2022

abayer force-pushed the api-reference-docs branch from b820618 to 69acedf Compare August 1, 2022 14:38

tekton-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 1, 2022

lbernick reviewed Aug 1, 2022

View reviewed changes

abayer force-pushed the api-reference-docs branch from 69acedf to 6d31e0f Compare August 1, 2022 14:52

abayer commented Aug 1, 2022

View reviewed changes

lbernick reviewed Aug 1, 2022

View reviewed changes

tekton-robot added the lgtm Indicates that a PR is ready to be merged. label Aug 1, 2022

tekton-robot merged commit 88fbc86 into tektoncd:main Aug 1, 2022

abayer mentioned this pull request Aug 11, 2022

Tekton API Reference #1250

Closed

This was referenced Oct 3, 2022

OpenSFF Best Practices Badge Program for Triggers tektoncd/triggers#1438

Closed

Automated API Reference generation tektoncd/triggers#1457

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generate API reference docs for Pipeline #4494

Generate API reference docs for Pipeline #4494

abayer commented Jan 18, 2022

abayer commented Jan 18, 2022

abayer commented Jan 18, 2022 •

edited

Loading

abayer commented Jan 18, 2022

abayer commented Jan 18, 2022

tekton-robot commented Jan 18, 2022

lbernick Jan 24, 2022

abayer Jan 24, 2022

lbernick commented Jan 24, 2022

abayer commented Jan 24, 2022

lbernick commented Jan 24, 2022

afrittoli Feb 16, 2022 •

edited

Loading

abayer Mar 21, 2022

abayer commented Mar 25, 2022

tekton-robot commented Jul 2, 2022

tekton-robot commented Aug 1, 2022

abayer commented Aug 1, 2022

tekton-robot commented Aug 1, 2022

abayer commented Aug 1, 2022

abayer commented Aug 1, 2022

lbernick Aug 1, 2022

abayer Aug 1, 2022

lbernick Aug 1, 2022

abayer Aug 1, 2022

lbernick Aug 1, 2022

abayer Aug 1, 2022

abayer Aug 1, 2022

lbernick Aug 1, 2022

lbernick left a comment

lbernick Aug 1, 2022

Generate API reference docs for Pipeline #4494

Generate API reference docs for Pipeline #4494

Conversation

abayer commented Jan 18, 2022

Changes

Submitter Checklist

Release Notes

abayer commented Jan 18, 2022

abayer commented Jan 18, 2022 • edited Loading

abayer commented Jan 18, 2022

abayer commented Jan 18, 2022

tekton-robot commented Jan 18, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lbernick commented Jan 24, 2022

abayer commented Jan 24, 2022

lbernick commented Jan 24, 2022

afrittoli Feb 16, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abayer commented Mar 25, 2022

tekton-robot commented Jul 2, 2022

tekton-robot commented Aug 1, 2022

abayer commented Aug 1, 2022

tekton-robot commented Aug 1, 2022

abayer commented Aug 1, 2022

abayer commented Aug 1, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lbernick left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abayer commented Jan 18, 2022 •

edited

Loading

afrittoli Feb 16, 2022 •

edited

Loading