gen-api-docs make target is not generating API docs for GameServerAllocation

[aLekSer]

Faced in #682.
There are bunch of errors while running make gen-api-docs from build folder, see them below.
Steps to reproduce:

1. git fetch https://github.com/GoogleCloudPlatform/agones.git pull/682/head:pr_682 && git checkout pr_682
2. make gen-api-docs

Expected:
site/content/en/docs/Reference/agones_crd_api_reference.html got updated.
Actual:
Only blank lines were added.

Current output of the script:

$ make gen-api-docs
docker run -e FILE="/go/src/agones.dev/agones/site/content/en/docs/Reference/agones_crd_api_reference.html" -e VERSION=0.10.0 --rm -i -v /Users/alexander.apalikov/go/src/agones.dev/agones/build//.confi$
/gcloud:/root/.config/gcloud -v ~/.kube/:/root/.kube -v ~/.helm:/root/.helm -v /Users/alexander.apalikov/go/src/agones.dev/agones:/go/src/agones.dev/agones -v /Users/alexander.apalikov/go/src/agones.de$
/agones/build//.gocache:/root/.cache/go-build agones-build:de8cde26b9 bash -c "/go/src/agones.dev/agones/site/gen-api-docs.sh"                                                                           
I0415 11:26:13.761044       8 main.go:116] parsing go packages in directory ../../../agones.dev/agones/pkg/apis/                                                                                         
W0415 11:26:28.459739       8 parse.go:239] Ignoring child directory agones.dev/agones/pkg/apis/allocation: unable to import "agones.dev/agones/pkg/apis/allocation": go/build: importGo agones.dev/agone$
/pkg/apis/allocation: exit status 1
go: finding agones.dev/agones/pkg/apis/allocation latest
go: finding agones.dev/agones/pkg/apis latest
go: finding agones.dev/agones/pkg latest
go: finding agones.dev/agones v0.9.0
go: downloading agones.dev/agones v0.9.0
go: extracting agones.dev/agones v0.9.0
can't load package: package agones.dev/agones/pkg/apis/allocation: unknown import path "agones.dev/agones/pkg/apis/allocation": cannot find module providing package agones.dev/agones/pkg/apis/allocation
W0415 11:26:30.195565       8 parse.go:239] Ignoring child directory agones.dev/agones/pkg/apis/allocation/v1alpha1: unable to import "agones.dev/agones/pkg/apis/allocation/v1alpha1": go/build: importGo
 agones.dev/agones/pkg/apis/allocation/v1alpha1: exit status 1
go: finding agones.dev/agones/pkg/apis/allocation/v1alpha1 latest
go: finding agones.dev/agones/pkg/apis/allocation latest
go: finding agones.dev/agones/pkg/apis latest
go: finding agones.dev/agones/pkg latest
can't load package: package agones.dev/agones/pkg/apis/allocation/v1alpha1: unknown import path "agones.dev/agones/pkg/apis/allocation/v1alpha1": cannot find module providing package agones.dev/agones/pkg/apis/allocation/v1alpha1

I0415 11:27:44.167386       8 main.go:202] using package=agones.dev/agones/pkg/apis/stable/v1alpha1
W0415 11:27:44.177908       8 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/util/intstr.IntOrString                                                                       
W0415 11:27:44.178572       8 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/types.UID                                                                                     
W0415 11:27:44.179261       8 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/types.UID                                                                                     
I0415 11:27:44.187743       8 main.go:150] written to /tmp/agones_crd_api_reference.html
{{% feature publishVersion="0.10.0" %}}

[aLekSer]

Hello @ahmetb Do you have an idea how we can treat this issue?
I think the issue is that we use remote version of the go files instead of local one:

go: downloading agones.dev/agones v0.9.0

Also I found a script which is used by Knative. They have separate repo for the docs.
https://github.com/knative/docs/blob/3c04f86ad7b7f937ae552a1b93eca97a5d312449/hack/gen-api-reference-docs.sh
Possibly we can change go.mod to use local modules.

[aLekSer]

As a workaround I found a way to replace dependencies to local modules:

cd /go/src/github.com/ahmetb/gen-crd-api-reference-docs

go mod edit --replace=agones.dev/agones@v0.9.0=../../../agones.dev/agones/
go build

It now updates the output html file.

[aLekSer]

With mentioned above fix, no errors on make gen-api-docs:

$ make gen-api-docs
docker run -e FILE="/go/src/agones.dev/agones/site/content/en/docs/Reference/agones_crd_api_reference.html" -e VERSION=0.10.0 --rm -i -v /Users/alexander.apalikov/go/src/agones.dev/agones/build//.config
/gcloud:/root/.config/gcloud -v ~/.kube/:/root/.kube -v ~/.helm:/root/.helm -v /Users/alexander.apalikov/go/src/agones.dev/agones:/go/src/agones.dev/agones -v /Users/alexander.apalikov/go/src/agones.dev
/agones/build//.gocache:/root/.cache/go-build agones-build:de8cde26b9 bash -c "/go/src/agones.dev/agones/site/gen-api-docs.sh"                                                                           
go: finding agones.dev/agones v0.9.0                                                                                                                                                                     
I0415 14:20:29.245838      96 main.go:116] parsing go packages in directory ../../../agones.dev/agones/pkg/apis/                                                                                         
I0415 14:21:52.738209      96 main.go:202] using package=agones.dev/agones/pkg/apis/allocation/v1alpha1                                                                                                  
I0415 14:21:52.738572      96 main.go:202] using package=agones.dev/agones/pkg/apis/stable/v1alpha1                                                                                                      
W0415 14:21:52.747680      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
W0415 14:21:52.749034      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
W0415 14:21:52.750720      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
W0415 14:21:52.752378      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
W0415 14:21:52.753636      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
W0415 14:21:52.754197      96 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/util/intstr.IntOrString                                                                       
W0415 14:21:52.754870      96 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/types.UID                                                                                     
W0415 14:21:52.755479      96 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/types.UID                                                                                     
W0415 14:21:52.758340      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
W0415 14:21:52.759396      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
W0415 14:21:52.760017      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
W0415 14:21:52.761757      96 main.go:343] not found external link source for type agones.dev/agones/pkg/apis.SchedulingStrategy                                                                         
I0415 14:21:52.765561      96 main.go:150] written to /tmp/agones_crd_api_reference.html
{{% feature publishVersion="0.10.0" %}}

[ahmetb]

Yeah, I recommend creating a dir with go.mod, then doing go mod download (or I guess in your case you'll use -replace to refer to an existing package on the filesystem) and run the tool there.

[aLekSer]

Thanks for your comment. So in our case only second approach with go mod edit --replace works, cause we want to have docs before commit, so that we can include them along with the package change.