search

Azure / azure-service-operator

Azure Service Operator allows you to create Azure resources using kubectl
https://azure.github.io/azure-service-operator/
MIT License
702 stars 188 forks source link

Show mandatory/optional properties in CRD docs #3146

Open theunrepentantgeek opened 11 months ago

theunrepentantgeek commented 11 months ago

Describe the current behavior

For many CRD properties, we have the information about whether the property is mandatory or not (we embed that in the source in the form of validation comments), but this is only visible in the generated docs if the narrative documentation happens to mention it.

Describe the improvement

We should add more information about field validation into our docs.

Additional context

Side issue: the author of gen-crd-api-reference-docs has indicated he's not really investing into the tool:

Nowadays, I don't have a lot of time to maintain this tool. So consider using one of the above in case this repo does not work for you.

We may need to consider moving to an alternative.

theunrepentantgeek commented 11 months ago

Based on this comment

Kubernetes gen-apidocs parser relies on running a kube-apiserver and calling /apis endpoint to get OpenAPI specs to generate docs.

We should also investigate https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-apidocs/generators

matthchr commented 1 month ago

Still interested in this, and I think at different times both @theunrepentantgeek and myself have written half a docs page generator, but maybe there's a good one out there now that does this automatically.