📖 Add docs: custom markers for unsupported file extensions

Fixes #4829

Author: nerdeveloper

docs/book/src/SUMMARY.md

@@ -130,6 +130,7 @@
   - [Extending](./plugins/extending.md)
     - [CLI and Plugins](./plugins/extending/extending_cli_features_and_plugins.md)
     - [External Plugins](./plugins/extending/external-plugins.md)
+    - [Custom Markers](./plugins/extending/custom-markers.md)
     - [E2E Tests](./plugins/extending/testing-plugins.md)
   - [Plugins Versioning](./plugins/plugins-versioning.md)
 

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

@@ -0,0 +1,349 @@
+# Creating Custom Markers for Unsupported File Extensions
+
+## Overview
+
+When building external plugins for Kubebuilder, you may need to scaffold files with extensions that aren't natively supported by Kubebuilder's marker system (such as `.rs` for Rust, `.java` for Java, `.tpl` for templates, etc.). This guide shows you how to use Kubebuilder as a library to create your own custom marker support for any file extension.
+
+## When to Use Custom Markers
+
+Custom markers are useful when:
+
+- 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
+
+## Understanding Markers
+
+Markers are special comments used by Kubebuilder for scaffolding purposes. They indicate where code can be inserted or modified. The core Kubebuilder marker system only supports `.go`, `.yaml`, and `.yml` files by default.
+
+Example of a marker in a Go file:
+```go
+// +kubebuilder:scaffold:imports
+```
+
+## Creating Custom Markers
+
+Instead of modifying Kubebuilder's core code, you can create your own marker implementation using Kubebuilder as a library. Here's how to implement custom markers for your specific file extensions.
+
+### Basic Custom Marker Implementation
+
+```go
+package plugin
+
+import (
+    "fmt"
+    "path/filepath"
+    "strings"
+
+    "sigs.k8s.io/kubebuilder/v4/pkg/machinery"
+)
+
+// Define your custom prefix for markers
+const myPluginPrefix = "+myplugin:scaffold:"
+
+// Map file extensions to their comment syntax
+var customCommentsByExt = map[string]string{
+    ".rs":   "//",  // Rust
+    ".java": "//",  // Java
+    ".py":   "#",   // Python
+    ".rb":   "#",   // Ruby
+    ".tpl":  "{{/* ", // Template files (with closing */}})
+}
+
+// CustomMarker extends the base Marker functionality
+type CustomMarker struct {
+    prefix  string
+    comment string
+    value   string
+}
+
+// NewCustomMarker creates a marker for your custom file extension
+func NewCustomMarker(path string, value string) (CustomMarker, error) {
+    ext := filepath.Ext(path)
+    comment, ok := customCommentsByExt[ext]
+    if !ok {
+        return CustomMarker{}, fmt.Errorf("unsupported file extension: %s", ext)
+    }
+
+    return CustomMarker{
+        prefix:  markerPrefix(myPluginPrefix),
+        comment: comment,
+        value:   value,
+    }, nil
+}
+
+// String implements the Stringer interface
+func (m CustomMarker) String() string {
+    // Special handling for template files
+    if m.comment == "{{/* " {
+        return m.comment + m.prefix + m.value + " */}}"
+    }
+    return m.comment + " " + m.prefix + m.value
+}
+
+// EqualsLine checks if a line contains this marker
+func (m CustomMarker) EqualsLine(line string) bool {
+    line = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(line), m.comment))
+    return line == m.prefix+m.value
+}
+
+// Helper function to format the marker prefix
+func markerPrefix(prefix string) string {
+    trimmed := strings.TrimSpace(prefix)
+    var builder strings.Builder
+    if !strings.HasPrefix(trimmed, "+") {
+        builder.WriteString("+")
+    }
+    builder.WriteString(trimmed)
+    if !strings.HasSuffix(trimmed, ":") {
+        builder.WriteString(":")
+    }
+    return builder.String()
+}
+```
+
+## Complete Example: Rust Plugin with Custom Markers
+
+Here's a complete example showing how to create an external plugin for Rust with custom marker support:
+
+### 1. Define Your Marker System
+
+```go
+// pkg/markers/rust.go
+package markers
+
+import (
+    "fmt"
+    "path/filepath"
+    "strings"
+)
+
+const RustPluginPrefix = "+rust:scaffold:"
+
+type RustMarker struct {
+    prefix  string
+    comment string
+    value   string
+}
+
+func NewRustMarker(path string, value string) (RustMarker, error) {
+    ext := filepath.Ext(path)
+    if ext != ".rs" {
+        return RustMarker{}, fmt.Errorf("expected .rs file, got %s", ext)
+    }
+
+    return RustMarker{
+        prefix:  formatPrefix(RustPluginPrefix),
+        comment: "//",
+        value:   value,
+    }, nil
+}
+
+func (m RustMarker) String() string {
+    return m.comment + " " + m.prefix + m.value
+}
+
+func formatPrefix(prefix string) string {
+    trimmed := strings.TrimSpace(prefix)
+    var builder strings.Builder
+    if !strings.HasPrefix(trimmed, "+") {
+        builder.WriteString("+")
+    }
+    builder.WriteString(trimmed)
+    if !strings.HasSuffix(trimmed, ":") {
+        builder.WriteString(":")
+    }
+    return builder.String()
+}
+```
+
+### 2. Create Scaffolding Templates
+
+```go
+// pkg/templates/main.go
+package templates
+
+import (
+    "path/filepath"
+    "sigs.k8s.io/kubebuilder/v4/pkg/machinery"
+    "github.com/yourorg/yourplugin/pkg/markers"
+)
+
+type RustMainFile struct {
+    machinery.TemplateMixin
+    machinery.ProjectNameMixin
+
+    // Add any additional fields your template needs
+    ModuleName string
+}
+
+// SetTemplateDefaults sets default values for the template
+func (f *RustMainFile) SetTemplateDefaults() error {
+    if f.Path == "" {
+        f.Path = filepath.Join("src", "main.rs")
+    }
+
+    // Create the marker for where additional code can be scaffolded
+    marker, err := markers.NewRustMarker(f.Path, "imports")
+    if err != nil {
+        return err
+    }
+
+    f.TemplateBody = fmt.Sprintf(`// Generated by Kubebuilder Rust Plugin
+%s
+
+use std::error::Error;
+
+%s
+
+fn main() -> Result<(), Box<dyn Error>> {
+    println!("Hello from %s!");
+    Ok(())
+}
+`, marker.String(), marker.String(), f.ProjectName)
+
+    return nil
+}
+```
+
+### 3. Integrate with External Plugin
+
+```go
+// cmd/main.go
+package main
+
+import (
+    "sigs.k8s.io/kubebuilder/v4/pkg/plugin"
+    "sigs.k8s.io/kubebuilder/v4/pkg/plugin/external"
+    "github.com/yourorg/yourplugin/pkg/templates"
+)
+
+func main() {
+    // Create and run your external plugin
+    p := &external.Plugin{
+        Name:    "rust.kubebuilder.io",
+        Version: plugin.Version{Number: 1, Stage: plugin.Alpha},
+
+        Init: func(req external.PluginRequest) external.PluginResponse {
+            // Create the main.rs file with markers
+            mainFile := &templates.RustMainFile{
+                ModuleName: "my_operator",
+            }
+
+            return external.PluginResponse{
+                Universe: req.Universe,
+                Files: []machinery.File{mainFile},
+            }
+        },
+    }
+
+    external.Run(p)
+}
+```
+
+## Additional Examples
+
+### Java Markers
+
+```go
+type JavaMarker struct {
+    prefix  string
+    comment string
+    value   string
+}
+
+func NewJavaMarker(path string, value string) (JavaMarker, error) {
+    ext := filepath.Ext(path)
+    if ext != ".java" {
+        return JavaMarker{}, fmt.Errorf("expected .java file, got %s", ext)
+    }
+
+    return JavaMarker{
+        prefix:  "+java:scaffold:",
+        comment: "//",
+        value:   value,
+    }, nil
+}
+```
+
+### Template File Markers
+
+```go
+type TemplateMarker struct {
+    prefix  string
+    value   string
+}
+
+func NewTemplateMarker(path string, value string) (TemplateMarker, error) {
+    ext := filepath.Ext(path)
+    if ext != ".tpl" && ext != ".tmpl" {
+        return TemplateMarker{}, fmt.Errorf("expected template file, got %s", ext)
+    }
+
+    return TemplateMarker{
+        prefix: "+template:scaffold:",
+        value:  value,
+    }, nil
+}
+
+func (m TemplateMarker) String() string {
+    return fmt.Sprintf("{{/* %s%s */}}", m.prefix, m.value)
+}
+```
+
+## Best Practices
+
+1. **Use Clear Prefixes**: Choose a unique prefix for your plugin to avoid conflicts (e.g., `+rust:scaffold:`, `+java:scaffold:`)
+
+2. **Handle Comments Correctly**: Different languages have different comment syntax. Make sure to map the correct comment style for each file extension.
+
+3. **Error Handling**: Always validate file extensions and return clear error messages when unsupported files are encountered.
+
+4. **Maintain Compatibility**: When possible, follow the same patterns as Kubebuilder's core marker system to maintain consistency.
+
+5. **Document Your Markers**: Clearly document what markers your plugin supports and where they should be placed.
+
+6. **Testing**: Test your marker implementation with various file types and edge cases.
+
+## Integration with Scaffolding
+
+When using custom markers in your scaffolding logic:
+
+```go
+func (s *Scaffolder) Execute() error {
+    // Read existing file
+    content, err := afero.ReadFile(s.fs, "src/main.rs")
+    if err != nil {
+        return err
+    }
+
+    // Create marker
+    marker, err := markers.NewRustMarker("src/main.rs", "imports")
+    if err != nil {
+        return err
+    }
+
+    // Find marker in content
+    lines := strings.Split(string(content), "\n")
+    for i, line := range lines {
+        if strings.Contains(line, marker.String()) {
+            // Insert new code after marker
+            newCode := "use my_crate::MyStruct;"
+            lines = append(lines[:i+1],
+                append([]string{newCode}, lines[i+1:]...)...)
+            break
+        }
+    }
+
+    // Write back to file
+    return afero.WriteFile(s.fs, "src/main.rs",
+        []byte(strings.Join(lines, "\n")), 0644)
+}
+```
+
+## Conclusion
+
+By creating custom markers, you can extend Kubebuilder's scaffolding capabilities to any language or file type without modifying Kubebuilder's core code. This approach maintains clean separation of concerns and allows external plugin developers to have full control over their scaffolding logic.
+
+For more information on creating external plugins, see [External Plugins](external-plugins.md).