Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Example Usage in Marker Code Documentation for Programmatic Docs Generation #1054

Open
camilamacedo86 opened this issue Sep 15, 2024 · 4 comments

Comments

@camilamacedo86
Copy link
Member

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
Copy link
Member

@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
Copy link
Member Author

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

Screenshot 2024-11-25 at 19 51 42

came from:

// +controllertools:marker:generateHelp:category="CRD validation"
// Default sets the default value for this field.
//
// A default value will be accepted as any value valid for the
// field. Formatting for common types include: boolean: `true`, string:
// `Cluster`, numerical: `1.24`, array: `{1,2}`, object: `{policy:
// "delete"}`). Defaults should be defined in pruned form, and only best-effort
// validation will be performed. Full validation of a default requires
// submission of the containing CRD to an apiserver.
type Default struct {
Value interface{}
}

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

@sbueringer
Copy link
Member

sbueringer commented Dec 20, 2024

Feel free to open PRs to improve this

@camilamacedo86
Copy link
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants