📖 Add docs: custom markers for unsupported file extensions #5107

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.

Sign up for GitHub

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

Jump to bottom

Open

nerdeveloper wants to merge 1 commit into kubernetes-sigs:master from nerdeveloper:docs/custom-markers-issue-4829

+171 −0

Contributor

nerdeveloper commented Sep 22, 2025

Summary

Adds documentation on creating custom markers for unsupported file extensions
Shows how to use Kubebuilder as a library for external plugins
Includes examples for Rust, Java, Python, and template files

Related

Fixes Add docs: how to create custom markers for unsupported file extensions #4829
Context from PR ✨ Marker support for Rust file extension .rs #4827

Test Plan

Documentation builds correctly
Code examples tested and compile without errors
Added to SUMMARY.md table of contents

k8s-ci-robot added the do-not-merge/invalid-commit-message label

k8s-ci-robot requested review from camilamacedo86 and Kavinjsir

September 22, 2025 21:53

Contributor

k8s-ci-robot commented Sep 22, 2025

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: nerdeveloper
Once this PR has been reviewed and has the lgtm label, please assign camilamacedo86 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot added cncf-cla: yes needs-ok-to-test size/L labels

Contributor

k8s-ci-robot commented Sep 22, 2025

Hi @nerdeveloper. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

nerdeveloper force-pushed the docs/custom-markers-issue-4829 branch from ddb8cdb to 161acff Compare

September 22, 2025 21:56

k8s-ci-robot removed the do-not-merge/invalid-commit-message label

camilamacedo86 reviewed

View reviewed changes

docs/book/src/plugins/extending/custom-markers.md Outdated

+              - You're building an **external plugin** for a language not natively supported by Kubebuilder
+              - You want to scaffold files with custom extensions (`.rs`, `.java`, `.tpl`, `.py`, etc.)
+              - Your file extensions aren't (and shouldn't be) part of the core `commentsByExt` map
+              - You need to maintain scaffolding markers in non-Go files

Member

camilamacedo86 Sep 24, 2025

I think the documentation could be How to create Custom Markers.
For those who use Kubebuilder as a library, it would be possible to create their own custom markers, regardless of whether it is for an extension valid or not for Golang projects.

So, it would not only be valid for external references

camilamacedo86 reviewed

View reviewed changes

docs/book/src/plugins/extending/custom-markers.md Outdated

+                      builder.WriteString(":")
+                  }
+                  return builder.String()
+              }

Member

camilamacedo86 Sep 24, 2025

Could you let me know if you tested this example?
Can it work without any change in the code at this moment?
Is the code covered with tests to ensure that this example would be possible?

camilamacedo86 reviewed

View reviewed changes

docs/book/src/plugins/extending/custom-markers.md Outdated

+              }
+              ```
+              ## Complete Example: Rust Plugin with Custom Markers

Member

camilamacedo86 Sep 24, 2025

Do we need all those examples?
Could we not have only 1 example?
How could we simplify the doc and its maintainability?
Just to share what is required

camilamacedo86 reviewed

View reviewed changes

docs/book/src/plugins/extending/custom-markers.md Outdated

Comment on lines 295 to 307

+              ## Best Practices
+. **Use Clear Prefixes**: Choose a unique prefix for your plugin to avoid conflicts (e.g., `+rust:scaffold:`, `+java:scaffold:`)
+. **Handle Comments Correctly**: Different languages have different comment syntax. Make sure to map the correct comment style for each file extension.
+. **Error Handling**: Always validate file extensions and return clear error messages when unsupported files are encountered.
+. **Maintain Compatibility**: When possible, follow the same patterns as Kubebuilder's core marker system to maintain consistency.
+. **Document Your Markers**: Clearly document what markers your plugin supports and where they should be placed.
+. **Testing**: Test your marker implementation with various file types and edge cases.

Member

camilamacedo86 Sep 24, 2025 •

edited

Loading

Best Practices is something subjective, I think it's better to avoid this term.

camilamacedo86 reviewed

View reviewed changes

docs/book/src/plugins/extending/custom-markers.md Outdated

+              }
+              ```
+              ## Conclusion

Member

camilamacedo86 Sep 24, 2025

Could you please review the other documentation we have?
We do not use a conclusion. We should always follow the same layout and standards.

Contributor Author

nerdeveloper commented Sep 27, 2025

Hi @camilamacedo86,

Thank you for the review feedback! I've updated the documentation to address your comments:

✅ Changed title to "Creating Custom Markers" (broader scope, not just for unsupported extensions)
✅ Simplified to only ONE example (Rust) instead of multiple examples
✅ Removed "Best Practices" section (subjective term)
✅ Removed "Conclusion" section (to match other docs)
✅ Made the documentation more concise and maintainable

Regarding testing: I performed minimal testing of the marker generation logic by creating a standalone Go program that tests the core marker creation code. The test confirms:

The code compiles without errors
Markers are generated with correct comment syntax for different file types (e.g., // +rust:scaffold:imports for Rust, # +python:scaffold:functions for Python)
The marker format is correct

However, I have NOT tested the complete integration with external plugins end-to-end (the full example with templates and plugin integration).

Question: What would you prefer for this documentation?

Keep the current example as a pattern/reference (with a note that it's not fully integration-tested)
Simplify further to only show the minimal testable code (just the marker creation)
Add a working example to an external test repository and link to it

Please let me know your preference, and I'll update accordingly!


          📖 Add docs: custom markers for unsupported file extensions

51faf4e

Shows how to use Kubebuilder as a library to create custom marker support
for external plugins with non-Go file extensions like .rs, .java, .py

nerdeveloper force-pushed the docs/custom-markers-issue-4829 branch from 161acff to 51faf4e Compare

September 27, 2025 10:39

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cncf-cla: yes needs-ok-to-test size/L