CRD docs integration

[jhkrug]

Do you like the look of this? I've just added the generated file contents into the page to see what it looks like.

@flavio , @viccuad , @jvanz

[netlify]

✅ Deploy Preview for silly-bunny-8cedd0 ready!

Name	Link
🔨 Latest commit	32df535
🔍 Latest deploy log	https://app.netlify.com/sites/silly-bunny-8cedd0/deploys/65290f7ae22a670008f9720f
😎 Deploy Preview	https://deploy-preview-263--silly-bunny-8cedd0.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[viccuad]

@jhkrug it's starting to look good, but the matchPolicy file entry breaks the rest of the table.
Compare with: https://doc.crds.dev/github.com/kubewarden/kubewarden-controller/policies.kubewarden.io/ClusterAdmissionPolicy/[email protected]#spec-matchPolicy

[viccuad]

This is personal preference, but I wonder if we could not generate the docs for old v1alpha versions, and only show v1, as happens in https://doc.crds.dev/github.com/kubewarden/kubewarden-controller/policies.kubewarden.io/AdmissionPolicy/[email protected] (see top right).

[flavio]

I think this is a step in the right direction. There are some minor rendering glitches as others pointed out, but I like it!

[jhkrug]

@jhkrug it's starting to look good, but the matchPolicy file entry breaks the rest of the table. Compare with: https://doc.crds.dev/github.com/kubewarden/kubewarden-controller/policies.kubewarden.io/ClusterAdmissionPolicy/[email protected]#spec-matchPolicy

This because the documentation source contains markdown for a list. A markdown list is not permitted in a markdown table cell. At least not in docusaurus. So, you can't put markdown formatting in the crd source. Plain, vanilla, unformatted text only. It's likely not to work. It works for asciidoc. Which we don't use, sadly perhaps.

[viccuad]

Maybe we can generate the crd docs in markdown instead, that could be a possibility too.

[jhkrug]

Maybe we can generate the crd docs in markdown instead, that could be a possibility too.

That's what I did for the demo. We can't use the default asciidoc.

[jhkrug]

I can take a look at the docs source file for this and try opening a PR in there.

[jhkrug]

@jhkrug it's starting to look good, but the matchPolicy file entry breaks the rest of the table. Compare with: https://doc.crds.dev/github.com/kubewarden/kubewarden-controller/policies.kubewarden.io/ClusterAdmissionPolicy/[email protected]#spec-matchPolicy

This because the documentation source contains markdown for a list. A markdown list is not permitted in a markdown table cell. At least not in docusaurus. So, you can't put markdown formatting in the crd source. Plain, vanilla, unformatted text only. It's likely not to work. It works for asciidoc. Which we don't use, sadly perhaps.

You can use a html list in policy_types.go and it works as well. So, that's another option.

[jhkrug]

So, it appears that the most you can get away with regarding docstring formatting is a html encoded list and list items. And I'd discourage that as well. Too prone to error and complications.

Some of the docstrings have code blocks in them. They don't work. I'd suggest an iteration of the docstrings. There is perhaps too much material in there. Keep it as short as possible, with links to doc pages as necessary for further explanations.

So why does it currently work? Well, different tool chains, but it doesn't really, particularly the namespaceSelector at the bottom.

[viccuad]

LGTM!
Super happy with this! This section was also the last one not accessible offline, now we can ship the docs together with the helm-charts, make them available even on airgap, or provide them in the UI!

[flavio]

This looks really good to me.

What about adding a more explicit link to that, right now this is kinda buried under sub-menus on the left sidebar.

I propose to do something like that:

If you're fine with that I can add this small change to this branch

[viccuad]

I'm ok with making the CRDs more explicit, maybe just under "Reference docs" and not "Reference docs -> Operator Manual".
I'm also ok linking to the CRDs docs from the CRD names in the quickstart (I don't understand much the shared screenshot).

[flavio]

I'm also ok linking to the CRDs docs from the CRD names in the quickstart (I don't understand much the shared screenshot).

Forgive me, I wasn't really explicit about the change I made. I've just added the new "TIP" section, the one in green.

[flavio]

thanks for the new changes!