Adjust API reference docs scripts for knative.dev

[bbrowning]

The API reference docs were failing to generate because they didn't
account for the change from github.com/knative/serving to
knative.dev/serving and similar for the eventing and eventing-contrib
repos.

[bbrowning]

I believe this fixes #1661

[RichieEscarez]

@bbrowning does that mean you are able to build the 0.11 ref docs successfully (ie. complete the steps here)?

[ahmetb]

Not sure how this fixes that.
What does the local_repo variable do? Did the import path for Knative go pkgs change?

[bbrowning]

@RichieEscarez Yes - the script works to generate the 0.11 docs, with one minor change due to me having Go 1.13 locally that requires GOPATH to be set for go mod and thus I have to uncomment the 3 lines in gen-api-reference-docs.sh that check to see if it's unset.

That's an unrelated, different issue either due to something in my environment or Go 1.13. But, either way, the reference API docs do generate successfully for recent Knative releases now.

[bbrowning]

@ahmetb yes, the Go import path for all the Knative repos changed to use the vanity knative.dev domain. Verbose output from the docs generation showed me that it was failing to resolve the Knative imports and thus leading to all the invalid type errors.

[ahmetb]

@bbrowning can you upload the resulting html somewhere like a gist? let's see if it fixes the issues I saw around type parsing.

[bbrowning]

I went ahead and opened a PR with the updated v0.11.0 reference docs in #2055. That PR is against master, but perhaps should be against the release-0.11 branch? Either way you should be able to see the diff as well as the new rendered markdown from that PR to check for anything else that still looks wrong.

[RichieEscarez]

Awesome! Thanks @bbrowning! I just ran your script and it worked for me too. Ill wait for the green light from @ahmetb before moving forward.

[ahmetb]

@RichieEscarez were you able to get serving generated correctly as well?
if so, let's go ahead with it.

[ahmetb]

let's rename _LOCAL_REPO to _IMPORT_PATH if you don't mind.

[RichieEscarez]

@ahmetb done, PTAL

[ahmetb]

I'm just surprised it works without fixing anything but that's cool.

[RichieEscarez]

Here are the staging preview build:

https://5df41e57527ac4000777c447--knative.netlify.com/docs/reference/serving-api/
https://5df41e57527ac4000777c447--knative.netlify.com/docs/reference/eventing/

@ahmetb yeah, i get the same output

[RichieEscarez]

Actually i found a broken artifact from using "knative.dev" -> all these links are now 404:

In serving-api:
https://knative.dev/serving/blob/master/docs/spec/overview.md#revision

("https://knative.dev" should instead point to "github.com")

[bbrowning]

@RichieEscarez Those broken links need updating in Knative Serving itself. There were erroneously replaced from their github.com URL in knative/serving#4521

[bbrowning]

knative/serving#6225 fixes the root issue in Serving so we won't have these broken links in our 0.12 release. I added a 2nd commit to #2055 to fix the links directly in the docs for 0.11 - the commit message for it includes the sed command I ran to automatically fix all of these, similar to the sed command used to fix this in Serving itself.

[RichieEscarez]

Zero broken links in the new preview build: https://5df42f87a20218f204084c22--knative.netlify.com/docs/reference/

Thanks @bbrowning!

@ahmetb any concerns with these changes? Can we merge?

[RichieEscarez]

Staging build looks good!

[knative-prow-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bbrowning, RichieEscarez

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 [RichieEscarez]

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

[ahmetb]

/lgtm