[Doc Broken] API Reference Types Definition

[a180285]

Description:
A clear and concise description of what the issue is.

The API page is broken: https://kubevirt.io/cdi-api-reference/main/definitions.html

What you expected:
A clear and concise description of what you expected.

URL:
Provide a link to the documentation.

https://kubevirt.io/cdi-api-reference/main/definitions.html

Additional context:
Add any other context about the issue here.

It broken after resource.Quantity

[alromeros]

Hey @a180285, thanks for the issue! Yeah, that doesn't seem right. I see the master branch of the repository seems ok https://github.com/kubevirt/api-reference/blob/3dcfdcc0084307ccbcc7b30978c86fd369138cb2/main/definitions.html#L2483, but since most of this code is automatically built the error might come from the API spec in Kubevirt. I'll take a look.

[alromeros]

Okay so this behavior seems to be caused by some formatting included in the description of the Quantity API in k8s (https://github.com/kubernetes/kubernetes/blob/41da26dbe15207cbe5b6c36b48a31d2cd3344123/staging/src/k8s.io/apimachinery/pkg/api/resource/quantity.go#L37-L57). Since these docs are automatically generated, the description is all condensed in a single line and lacks the \n needed to close the formatting.

I can open a PR in kubevirt and fix it, but probably will be updated to the current state every time we run make generate. I'll let you know if I'm able to fix it.

Edit: Even if I were able to fix the formatting, the doc for quantity wouldn't still look good since the generator does not include newlines when it should...

Edit2: This formatting is also causing some problems in k8s own documentation kubernetes/website#35712

[alromeros]

Hey @rmohr, pingin you since I see you regularly commit to the api-reference repository. Do you know if we can disable the clode-block formatting from our api-reference? I see k8s is having a similar problem with formatting but their page doesn't render the code block, so at least the rest of their documentation isn't messed up. Thanks!

[rmohr]

@alromeros can't you just perform some modifications of the generated spec in the repo? Like some regexp modifications? The api-reference is automatically built and pushed. I think it just used my bot account a long time ago.

Here some examples where we are fixing something which will survive make generate and the like: https://github.com/kubevirt/kubevirt/blob/main/hack/gen-swagger-doc/gen-swagger-docs.sh#L71

[alromeros]

Thanks for the suggestion @rmohr, will take a look!

[rmohr]

I can open a PR in kubevirt and fix it, but probably will be updated to the current state every time we run make generate. I'll let you know if I'm able to fix it.

Oh, and I think CDI does all this independent of kubevirt. So you probably want to fix this in this repo.

[alromeros]

With the fix in the code-generator the api-reference should look fine now. Closing the issue, thanks @rmohr for the help and @a180285 for the report!