Agones: Documentation for the extended Kubernetes API

[markmandel]

When we implement CRDs for Agones, we create new API endpoints for each CRD.

It would be great to document these, and publish it somewhere, so that people can more easily integrate, and we can reference it in our documentation.

I feel there are several steps:

1. [ ] Create a make target that generates the documentation
2. [ ] Determine where it can be hosted (App engine?), integrate it into our build system and domain controls (@markmandel would need to do this part, most likely)

Resources

• Kubebuilder has a tool, maybe we can leverage that - https://book.kubebuilder.io/beyond_basics/generating_documentation.html

[markmandel]

This is currently blocked by: https://github.com/kubernetes-sigs/kubebuilder/issues/483

Will wait for it to get fixed.

[markmandel]

Another tool to try out: https://github.com/ahmetb/gen-crd-api-reference-docs (this looks way more promising)

[ahmetb]

Any interest? I can help you get this done in ~20 minutes.

[markmandel]

Yep, definitely! Just haven't got to it yet!

Will need to integrate it into our build image, and our Make targets so we can regenerate on model change though!

[aLekSer]

I see that Kubebuilder has an issue and functionality "Generate docs" seems to be not supported yet.
https://github.com/kubernetes-sigs/kubebuilder/issues/483
Therefore this @ahmetb's project gen-crd-api-reference-docs would be really helpful.
@markmandel I can help with this task. By the way should we integrate all these pages to Hugo ?

[markmandel]

Yeah, if there is a way we can integrate this into agones.dev somehow, I think that would be ideal :+1:

Maybe whenever we run make site-static is generates the API?

[aLekSer]

I need to investigate more on how generated docs would look like and how to integrate them into site-static flow.

[markmandel]

@aLekSer can we close this now?

[markmandel]

Whoops - hit the wrong button, but @aLekSer should we reopon this?

[aLekSer]

Agree with closing that, I think the main part is done, the rest is to polish current version, only some small warnings while parsing "./pkg/apis/stable/v1alpha1/" occurred:

I0401 07:45:21.445044       8 main.go:116] parsing go packages in directory ../../../agones.dev/agones/pkg/apis/stable/v1alpha1/
I0401 07:47:56.364115       8 main.go:202] using package=agones.dev/agones/pkg/apis/stable/v1alpha1
W0401 07:47:56.392406       8 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/util/intstr.IntOrString
W0401 07:47:56.393399       8 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/types.UID
W0401 07:47:56.394154       8 main.go:343] not found external link source for type k8s.io/apimachinery/pkg/types.UID

[ahmetb]

Yeah we can probably make them lower level logs instead of warnings. If they bother you, feel free to make small PR to the generator!