Add Example Usage in Marker Code Documentation for Programmatic Docs Generation

[camilamacedo86]

It would be great if controller-tools begins adding examples directly into the code documentation for the markers, so that the Kuebuilder documentation can be programmatically generated with examples included and make its usage much more simplified.

Context

Currently, Kubebuilder generates its documentation programmatically using the machinery outlined here and the process described here. However, marker documentation is often difficult to understand without practical examples of how to use each marker in context. Including examples in the code documentation would significantly improve the quality of the generated documentation.

Thank you for considering this enhancement! IHMO It will greatly improve the user experience for developers working with markers in controller-tools.

[sbueringer]

@camilamacedo86 Can you maybe open a PR to add an example to one of the markers. Just to show how this would be done?

I think from then on it would be easy for others to contribute for other markers

[camilamacedo86]

Hi @sbueringer

Basically, the idea here would be to add examples of the usage within the description. For example, for: https://book.kubebuilder.io/reference/markers/crd-validation

came from: https://github.com/kubernetes-sigs/controller-tools/blob/425b7d770a963e4b4cdcd389b85c8501287a97f3/pkg/crd/markers/validation.go#L233-L244

Could we ensure that we have in those comments/golang docs the options along with the description example of usage?

[sbueringer]

Feel free to open PRs to improve this

[camilamacedo86]

I will try asap I have a some time, but if anyone from community want to work on it please feel free It would be a great help.

[sbueringer]

Sure, no rush :)

/help

[k8s-ci-robot]

@sbueringer: This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed by commenting with the /remove-help command.

In response to this:

/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.