📖 Improve collapsible code sections and formatting of tutorials

docs/book/book.toml

@@ -21,4 +21,3 @@ command = "./markerdocs.sh"
 
 [context.deploy-preview.environment]
   environment = { GO_VERSION = "1.23" }
-

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,6 @@ 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

@@ -170,6 +170,8 @@ var _ = AfterSuite(func() {
 	Expect(err).NotTo(HaveOccurred())
 })
 
+// +kubebuilder:docs-gen:collapse=Remaining code from suite_test.go
+
 /*
 Now that you have your controller running on a test cluster and a client ready to perform operations on your CronJob, we can start writing integration tests!
 */

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.
@@ -279,4 +279,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_conversion.go

@@ -90,8 +90,7 @@ func (src *CronJob) ConvertTo(dstRaw conversion.Hub) error {
 	dst.Status.Active = src.Status.Active
 	dst.Status.LastScheduleTime = src.Status.LastScheduleTime
 
-	// +kubebuilder:docs-gen:collapse=rote conversion
-
+	// +kubebuilder:docs-gen:collapse=rest of conversion Code Implementation
 	return nil
 }
 
@@ -141,7 +140,6 @@ func (dst *CronJob) ConvertFrom(srcRaw conversion.Hub) error {
 	dst.Status.Active = src.Status.Active
 	dst.Status.LastScheduleTime = src.Status.LastScheduleTime
 
-	// +kubebuilder:docs-gen:collapse=rote conversion
-
+	// +kubebuilder:docs-gen:collapse=rest of conversion Code Implementation
 	return nil
 }

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

@@ -83,11 +83,10 @@ type CronJobSpec struct {
 	// +optional
 	// +kubebuilder:validation:Minimum=0
 	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
-
-	// +kubebuilder:docs-gen:collapse=The rest of Spec
-
 }
 
+// +kubebuilder:docs-gen:collapse=CronJobSpec Full Code
+
 /*
 Next, we'll need to define a type to hold our schedule.
 Based on our proposed YAML above, it'll have a field for

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.
@@ -225,8 +224,7 @@ func main() {
 	}
 	// +kubebuilder:scaffold:builder
 
-	/*
-	 */
+	// +kubebuilder:docs-gen:collapse=Remaining code from main.go
 
 	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
 		setupLog.Error(err, "unable to set up health check")
@@ -242,5 +240,8 @@ 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
+
+// +kubebuilder:docs-gen:collapse=Remaining code from main.go

docs/book/src/multiversion-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/multiversion-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/multiversion-tutorial/testdata/project/internal/controller/suite_test.go

@@ -170,6 +170,8 @@ var _ = AfterSuite(func() {
 	Expect(err).NotTo(HaveOccurred())
 })
 
+// +kubebuilder:docs-gen:collapse=Remaining code from suite_test.go
+
 /*
 Now that you have your controller running on a test cluster and a client ready to perform operations on your CronJob, we can start writing integration tests!
 */

docs/book/src/multiversion-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.
@@ -284,4 +284,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/internal/webhook/v2/cronjob_webhook.go

@@ -13,6 +13,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 */
+// +kubebuilder:docs-gen:collapse=Apache License
 
 package v2