Generate API docs

[tnozicka]

Description of your changes:
The PR add a tool (gen-api-reference) that can generate API docs from CRDs. While it has it's quirks, like the inlined objects from other or the same API group, it is marginally better then not having to the docs at all. Compared to native Swagger/OpenAPI this is aware of API groups and versions.

The next step would be to generate the docs base on Golang types that don't inline referenced objects but this still gets us 95% of the way and with the internal links to objects it's quite usable.

Which issue is resolved by this Pull Request:
Resolves #1526

[rzetelskik]

Two questions before I go into reviewing this:

1. Why did you choose generating rst instead of markdown?

The next step would be to generate the docs base on Golang types

Couldn't it be handled similarly to how https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs handles it?

[tnozicka]

Why did you choose generating rst instead of markdown?

We need the RST directives so embedding it in markdown just makes it harder or possibly bumping into "convertor" issues. Some like toc may not be even supported there. That said, it's limited to the templates.

Couldn't it be handled similarly to how https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs handles it?

I think we'll eventually use a similar generator from GoType, I didn't realize CRDs lack some of the information initially and this was quick to get. I'd like it to be slightly less manually but will see when I do v2 on types one day.

(You can cut this PR some slack as we'll eventually replace it.)

[rzetelskik]

We need the RST directives so embedding it in markdown just makes it harder or possibly bumping into "convertor" issues. Some like toc may not be even supported there. That said, it's limited to the templates.

toc is supported - mystparser docs are dogfooding https://github.com/executablebooks/MyST-Parser/blob/master/docs/index.md. Having said that our indexes are still in rst so not an issue, this can be converted later, I was just curious if there was a known blocker. I'd personally rather see all our docs in markdown than the other way round but let's not get into this here.

[tnozicka]

Good, I am fine if this eventually reconciles one way or the other, if we decide to unify the rest. If we sort it out for the rest, the templates are easy to switch.

[tnozicka]

@rzetelskik gentle ping

[rzetelskik]

@rzetelskik gentle ping

on it ;)

[rzetelskik]

lgtm overall, a few comments.
I wonder - would it be possible to indent nested fields, like Kube API reference does? Or does that require moving to parsing go files?

[tnozicka]

would it be possible to indent nested fields

I think they selectively inline some definitions and the others. This is tricky and you may end up defining some multiple times. I'd rather not go into it here.

[tnozicka]

#1546 (comment)
/retest

[rzetelskik]

one more comment, other than that lgtm
/assign zimnx

[rzetelskik]

/approve
and lgtm

[scylla-operator-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: rzetelskik, tnozicka

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [tnozicka]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[tnozicka]

one more comment, other than that lgtm
/assign zimnx

@rzetelskik based on your previous comment (and resolving the referenced nit) I suppose this is now only awaiting your official tag?

[rzetelskik]

/unassign zimnx
/lgtm