Cloud-on-k8s: API doc generation fails when project not in GOPATH

[pebrc]

If the project is not checked out in GOPATH the api doc generation step fails with

>> Generating API reference documentation...
F1111 15:20:43.219462    8904 main.go:134] no API packages found in ./pkg/apis
goroutine 1

After discussing with @charith-elastic it seems that

When outside the GOPATH, the generator only works if both the following conditions are met:

1. cloud-on-k8s and gen-crd-api-reference-docs must have a common parent directory
2. The generator executable must be called from the gen-crd-api-reference-docs directory

[charith-elastic]

Even when the generator works outside the GOPATH, links to certain types are lost. This is probably because the gengo library is not module-aware.

diff --git a/docs/api-docs.asciidoc b/docs/api-docs.asciidoc
index 9b96067c..11a821ef 100644
--- a/docs/api-docs.asciidoc
+++ b/docs/api-docs.asciidoc
@@ -55,15 +55,15 @@ Version of the APM Server.
 Image is the APM Server Docker image to deploy.
 *`count`*  _int32_::
 Count of APM Server instances to deploy.
-*`config`* _xref:common-k8s-elastic-co-v1beta1-config[$$Config$$]_::
+*`config`*  _github.com/elastic/cloud-on-k8s/pkg/apis/common/v1beta1.Config_::
 Config holds the APM Server configuration. See: https://www.elastic.co/guide/en/apm/server/current/configuring-howto-apm-server.html
-*`http`* _xref:common-k8s-elastic-co-v1beta1-httpconfig[$$HTTPConfig$$]_::
+*`http`*  _github.com/elastic/cloud-on-k8s/pkg/apis/common/v1beta1.HTTPConfig_::
 HTTP holds the HTTP layer configuration for the APM Server resource.
-*`elasticsearchRef`* _xref:common-k8s-elastic-co-v1beta1-objectselector[$$ObjectSelector$$]_::
+*`elasticsearchRef`*  _github.com/elastic/cloud-on-k8s/pkg/apis/common/v1beta1.ObjectSelector_::
 ElasticsearchRef is a reference to the output Elasticsearch cluster running in the same Kubernetes cluster.
 *`podTemplate`* _link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#podtemplatespec-v1-core[$$Kubernetes core/v1.PodTemplateSpec$$]_::
 PodTemplate provides customisation options (labels, annotations, affinity rules, resource requests, and so on) for the APM Server pods.
-*`secureSettings`* _xref:common-k8s-elastic-co-v1beta1-secretsource[$$[]SecretSource$$]_::
+*`secureSettings`*  _[]github.com/elastic/cloud-on-k8s/pkg/apis/common/v1beta1.SecretSource_::

[charith-elastic]

I wrote a new API doc generator that supports Go modules and is much faster (takes about 500ms compared to over 60s taken by the existing tool). It's currently in a private repository until licensing details can be sorted out.

Output generated by the new tool: https://gist.github.com/charith-elastic/024dae2e08e78927423b213b3f5a9946