Replace gen-crd-api-reference-docs for API documentation generation

[ArthurSens]

In #6001 we noticed that inline structs in our API are not reflected by gen-crd-api-reference-docs.

The author of gen-crd-api-reference-docs also mentions how the tool is not maintained anymore and other options, like elastic/crd-ref-docs, have already fixed the inline structs problem.

We want to move away from gen-crd-api-reference-docs for the reasons above

[slashpai]

I cleared my assignment as I didnt get enough time to work on this one but this can be a good one to get started for GSoc :)

[haanhvu]

I cleared my assignment as I didnt get enough time to work on this one but this can be a good one to get started for GSoc :)

@slashpai maybe a good first issue tag so that folks can find?

[ArthurSens]

I haven't put the label before because I like CNCF's guidelines for labeling something with good-first-issue, I'll try to improve the issue description later 😬

[slashpai]

@ArthurSens sure, I think since replacing the gen library doesn't need to have prometheus-operator knowledge much it can be a tackle for someone familiar with go as well. Do you want to remove good first label on this?

[ArthurSens]

@ArthurSens sure, I think since replacing the gen library doesn't need to have prometheus-operator knowledge much it can be a tackle for someone familiar with go as well. Do you want to remove good first label on this?

nah let's keep it :)

[mouad-eh]

just showing interest for working on this (already started in fact). I will follow up with a PR in the upcoming days.

[mouad-eh]

I have been experimenting with elastic/crd-ref-docs today and here are some important notes I took:

• If we want to migrate to this tool, we cannot just change the binary and expect everthing to work seamlessly because this fork is a lot different from the original repo. Both config file and templates needs to be changed as they have different fields and structure.
• It is true that this fork support type embedding but It didn't work when I tried it with prometheus-operator api files. the reason is that pointers are used for the type embedding (in the case of ProxyConfig) and they do not support that, they only support struct types embedding.
• // +kubebuilder:object:root=true need to be added as a comment to highlight resource types from other types.
• When I tried the default templates provided on their repo , I found that resource types are not listed first before other types and they rely strictly on the alphabetical order for sorting.

@slashpai @ArthurSens your thoughts on this?

[ArthurSens]

Thanks for taking a look!

• If we want to migrate to this tool, we cannot just change the binary and expect everthing to work seamlessly because this fork is a lot different from the original repo. Both config file and templates needs to be changed as they have different fields and structure.

Yeah, that was expected I guess... no problems in changing everything, it's just a lot of work 😬

• It is true that this fork support type embedding but It didn't work when I tried it with prometheus-operator api files. the reason is that pointers are used for the type embedding (in the case of ProxyConfig) and they do not support that, they only support struct types embedding.

Oh damn, that's a boomer. I'm not sure what would be the impact if we change this, maybe that's fine to change?

• // +kubebuilder:object:root=true need to be added as a comment to highlight resource types from other types.
• When I tried the default templates provided on their repo , I found that resource types are not listed first before other types and they rely strictly on the alphabetical order for sorting.

That's an easy fix :) no problems adding that annotation and no problems sorting things alphabetically

[haanhvu]

#6400 has been fixed. Seems like that has fixed this issue too?

[mouad-eh]

Yes definitely. I thought the two issues were closed. However, if embedded struct pointers are used again the issue may reappear. That's why it is still open I guess.

[ArthurSens]

The tool we're using is still deprecated, in my opinion we still want to replace it 😬