search

kubernetes-sigs / controller-tools

Tools to use with the controller-runtime libraries
Apache License 2.0
736 stars 420 forks source link

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

Open camilamacedo86 opened 2 months ago

camilamacedo86 commented 2 months ago

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 commented 2 months ago

@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