Improve docs layout and snipt code from tutorials

Assisted-by: Cursor

Author: camilamacedo86

docs/book/book.toml

@@ -7,8 +7,13 @@ title = "The Kubebuilder Book"
 [output.html]
 smart-punctuation = true
 additional-css = ["theme/css/markers.css", "theme/css/custom.css", "theme/css/version-dropdown.css"]
+additional-js = ["functions/copy-code.js"]
 git-repository-url = "https://github.com/kubernetes-sigs/kubebuilder"
 edit-url-template = "https://github.com/kubernetes-sigs/kubebuilder/edit/master/docs/book/{path}"
+# Enable copy button on code blocks  
+copy-fonts = true
+# Improve code block rendering
+code-block-copy-button = true
 
 [preprocessor.literatego]
 command = "./litgo.sh"

docs/book/functions/copy-code.js

@@ -0,0 +1,88 @@
+/*
+ * Add copy buttons to code blocks
+ * Enhances usability by allowing users to easily copy code snippets
+ */
+
+(function() {
+    'use strict';
+    
+    // Wait for page to load
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', addCopyButtons);
+    } else {
+        addCopyButtons();
+    }
+
+    function addCopyButtons() {
+        // Find all code blocks in .literate sections and regular pre blocks
+        var codeBlocks = document.querySelectorAll('pre:has(code)');
+        
+        codeBlocks.forEach(function(pre) {
+            // Skip if button already exists or if it's inside a summary (collapse header)
+            if (pre.querySelector('.copy-button') || pre.closest('summary')) {
+                return;
+            }
+            
+            // Create buttons container
+            var buttonsDiv = document.createElement('div');
+            buttonsDiv.className = 'buttons';
+            buttonsDiv.style.cssText = 'position: absolute; right: 5px; top: 5px; display: flex; gap: 4px;';
+            
+            // Create copy button
+            var copyButton = document.createElement('button');
+            copyButton.className = 'fa fa-copy copy-button';
+            copyButton.setAttribute('aria-label', 'Copy code to clipboard');
+            copyButton.setAttribute('title', 'Copy');
+            copyButton.style.cssText = 'cursor: pointer; padding: 4px 8px; background: var(--sidebar-bg); border: 1px solid var(--sidebar-fg); border-radius: 3px; color: var(--sidebar-fg); font-size: 14px;';
+            
+            // Make pre position relative so button can be absolutely positioned
+            if (window.getComputedStyle(pre).position === 'static') {
+                pre.style.position = 'relative';
+            }
+            
+            // Add click handler
+            copyButton.addEventListener('click', function() {
+                var code = pre.querySelector('code');
+                var text = code ? code.innerText : pre.innerText;
+                
+                // Use clipboard API
+                if (navigator.clipboard) {
+                    navigator.clipboard.writeText(text).then(function() {
+                        copyButton.innerHTML = '<i class="fa fa-check"></i>';
+                        copyButton.setAttribute('title', 'Copied!');
+                        setTimeout(function() {
+                            copyButton.innerHTML = '<i class="fa fa-copy"></i>';
+                            copyButton.setAttribute('title', 'Copy');
+                        }, 2000);
+                    }).catch(function(err) {
+                        console.error('Failed to copy: ', err);
+                    });
+                } else {
+                    // Fallback for older browsers
+                    var textarea = document.createElement('textarea');
+                    textarea.value = text;
+                    textarea.style.position = 'fixed';
+                    textarea.style.opacity = '0';
+                    document.body.appendChild(textarea);
+                    textarea.select();
+                    try {
+                        document.execCommand('copy');
+                        copyButton.innerHTML = '<i class="fa fa-check"></i>';
+                        copyButton.setAttribute('title', 'Copied!');
+                        setTimeout(function() {
+                            copyButton.innerHTML = '<i class="fa fa-copy"></i>';
+                            copyButton.setAttribute('title', 'Copy');
+                        }, 2000);
+                    } catch (err) {
+                        console.error('Failed to copy: ', err);
+                    }
+                    document.body.removeChild(textarea);
+                }
+            });
+            
+            buttonsDiv.appendChild(copyButton);
+            pre.insertBefore(buttonsDiv, pre.firstChild);
+        });
+    }
+})();
+

docs/book/src/cronjob-tutorial/testdata/project/cmd/main.go

@@ -198,7 +198,7 @@ func main() {
 		os.Exit(1)
 	}
 
-	// +kubebuilder:docs-gen:collapse=old stuff
+	// +kubebuilder:docs-gen:collapse=Remaining code from main.go
 
 	if err := (&controller.CronJobReconciler{
 		Client: mgr.GetClient(),
@@ -239,5 +239,5 @@ func main() {
 		setupLog.Error(err, "problem running manager")
 		os.Exit(1)
 	}
-	// +kubebuilder:docs-gen:collapse=old stuff
+	// +kubebuilder:docs-gen:collapse=Remaining code from main.go
 }

docs/book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller.go

@@ -68,7 +68,7 @@ type Clock interface {
 	Now() time.Time
 }
 
-// +kubebuilder:docs-gen:collapse=Clock
+// +kubebuilder:docs-gen:collapse=Clock Code Implementation
 
 // Definitions to manage status conditions
 const (

docs/book/src/cronjob-tutorial/testdata/project/internal/controller/cronjob_controller_test.go

@@ -208,6 +208,8 @@ var _ = Describe("CronJob controller", func() {
 
 })
 
+// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_controller_test.go
+
 /*
 	After writing all this code, you can run `go test ./...` in your `controllers/` directory again to run your new test!
 */

docs/book/src/cronjob-tutorial/testdata/project/internal/controller/suite_test.go

@@ -168,6 +168,7 @@ var _ = AfterSuite(func() {
 	cancel()
 	err := testEnv.Stop()
 	Expect(err).NotTo(HaveOccurred())
+	// +kubebuilder:docs-gen:collapse=Remaining code from suite_test.go
 })
 
 /*

docs/book/src/cronjob-tutorial/testdata/project/internal/webhook/v1/cronjob_webhook.go

@@ -36,7 +36,7 @@ import (
 	batchv1 "tutorial.kubebuilder.io/project/api/v1"
 )
 
-// +kubebuilder:docs-gen:collapse=Go imports
+// +kubebuilder:docs-gen:collapse=Imports
 
 /*
 Next, we'll setup a logger for the webhooks.
@@ -277,4 +277,4 @@ func validateCronJobName(cronjob *batchv1.CronJob) *field.Error {
 	return nil
 }
 
-// +kubebuilder:docs-gen:collapse=Validate object name
+// +kubebuilder:docs-gen:collapse=validateCronJobName() Code Implementation

docs/book/src/multiversion-tutorial/testdata/project/api/v1/cronjob_types.go

@@ -131,7 +131,7 @@ type CronJobStatus struct {
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 }
 
-// +kubebuilder:docs-gen:collapse=old stuff
+// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_types.go
 
 /*
  Since we'll have more than one version, we'll need to mark a storage version.
@@ -183,4 +183,4 @@ func init() {
 	SchemeBuilder.Register(&CronJob{}, &CronJobList{})
 }
 
-// +kubebuilder:docs-gen:collapse=old stuff
+// +kubebuilder:docs-gen:collapse=Remaining code from cronjob_types.go

docs/book/src/multiversion-tutorial/testdata/project/api/v2/cronjob_types.go

@@ -84,7 +84,7 @@ type CronJobSpec struct {
 	// +kubebuilder:validation:Minimum=0
 	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
 
-	// +kubebuilder:docs-gen:collapse=The rest of Spec
+	// +kubebuilder:docs-gen:collapse=CronJobSpec Full Code
 
 }
 

docs/book/src/multiversion-tutorial/testdata/project/cmd/main.go

@@ -204,7 +204,6 @@ func main() {
 		setupLog.Error(err, "unable to create controller", "controller", "CronJob")
 		os.Exit(1)
 	}
-	// +kubebuilder:docs-gen:collapse=existing setup
 
 	/*
 		Our existing call to SetupWebhookWithManager registers our conversion webhooks with the manager, too.
@@ -242,5 +241,5 @@ func main() {
 		setupLog.Error(err, "problem running manager")
 		os.Exit(1)
 	}
-	// +kubebuilder:docs-gen:collapse=existing setup
+	// +kubebuilder:docs-gen:collapse=Remaining code from main.go
 }