Generate reference documentation automatically from godocs in the API

[mdbooth]

/kind feature

We should automatically generate user-referenceable documentation for our APIs from the APIs themselves. We should publish them in/with the CAPO book.

Whether the documentation is generated directly from the API or indirectly via the CRDs is not important. We should investigate how this is solved in other projects to determine existing best practise.

[mdbooth]

/help

[k8s-ci-robot]

@mdbooth:
This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/help

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.

[lentzi90]

Since CAPO was created as a kubebuilder project, I think this should be useful to us: https://book-v1.book.kubebuilder.io/beyond_basics/generating_documentation

[mdbooth]

Since CAPO was created as a kubebuilder project, I think this should be useful to us: https://book-v1.book.kubebuilder.io/beyond_basics/generating_documentation

This looks ideal, but I can't see any reference to it in the v2 docs at first glance.

[alexandrevilain]

Hi!

I think that you might use ahmetb/gen-crd-api-reference-docs.

It's used in many well-known projects and I use it in a personal project, it works like a charm. For instance: https://github.com/alexandrevilain/temporal-operator/blob/main/docs/api/v1beta1.md

[mdbooth]

Hi!

I think that you might use ahmetb/gen-crd-api-reference-docs.

It's used in many well-known projects and I use it in a personal project, it works like a charm. For instance: https://github.com/alexandrevilain/temporal-operator/blob/main/docs/api/v1beta1.md

That looks good!

[alexandrevilain]

I created a PR using ahmetb/gen-crd-api-reference-docs.

I hope it can help.