feat(docs): add @Sample annotation for documentation

[Choconaut]

Marks integration test classes so that markdown pages can be auto generated.

[Choconaut]

I wasn't sure where to place @sample, so I put it in a temporary module for now. I thought about putting it in sample-operators. Do you have any recommendations? I'm happy to move it.

[csviri]

I think that is fine by now, since the implementation will be I guess an annotation processor.

[Copilot]

Pull Request Overview

This PR introduces a @Sample annotation and corresponding annotation processor to enable automatic generation of markdown documentation from integration test classes. The feature allows developers to mark test classes with metadata that gets compiled into a samples.md file for documentation purposes.

• Adds a new @Sample annotation with tldr and description fields for marking integration test classes
• Implements a SampleProcessor annotation processor that collects annotated classes and generates markdown output
• Creates a new Maven module operator-annotations to house the annotation infrastructure

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
pom.xml	Adds the new operator-annotations module to the parent POM
operator-annotations/pom.xml	Defines the new Maven module for annotation processing
operator-annotations/src/main/java/io/javaoperatorsdk/annotation/Sample.java	Defines the @sample annotation with tldr and description fields
operator-annotations/src/main/java/io/javaoperatorsdk/processor/SampleProcessor.java	Implements the annotation processor that generates samples.md from annotated classes

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[csviri]

Hi @Choconaut , looks good maybe what we could do is to use this now in operator-framework module and annotate one test with the annotation and see how the result looks.

[Choconaut]

Hi @Choconaut , looks good maybe what we could do is to use this now in operator-framework module and annotate one test with the annotation and see how the result looks.

Hi, I added the sample annotations to these 2 classes: RDMappingInTestExtensionIT.java, ChangeNamespaceIT.java in operator-framework. Let me know if there's anything I should change.

[csviri]

Hi @Choconaut , looks good maybe what we could do is to use this now in operator-framework module and annotate one test with the annotation and see how the result looks.

Hi, I added the sample annotations to these 2 classes: RDMappingInTestExtensionIT.java, ChangeNamespaceIT.java in operator-framework. Let me know if there's anything I should change.

thank you will take a look next week

[csviri]

We should use ${project.version} here.

[csviri]

Hi @Choconaut pls rebase it on to main and fix the build, I also tried it to locally but does not seem to generate the file, is it working for you locally?

[csviri]

Hi @Choconaut I'm sorry but wanted to make progress with this, and quickly implemented this today:

#3052

feel free to make improvements on that later.