docs: remove examples from generated files

cmd/talosctl/cmd/mgmt/gen/config.go

@@ -71,8 +71,6 @@ var genConfigCmdFlags struct {
 	configPatchWorker       []string
 	registryMirrors         []string
 	persistConfig           bool
-	withExamples            bool
-	withDocs                bool
 	withClusterDiscovery    bool
 	withKubeSpan            bool
 	withSecrets             string
@@ -235,13 +233,6 @@ func writeConfig(args []string) error {
 	)
 
 	commentsFlags := encoder.CommentsDisabled
-	if genConfigCmdFlags.withDocs {
-		commentsFlags |= encoder.CommentsDocs
-	}
-
-	if genConfigCmdFlags.withExamples {
-		commentsFlags |= encoder.CommentsExamples
-	}
 
 	configBundle, err := GenerateConfigBundle(
 		genOptions,
@@ -440,8 +431,6 @@ func init() {
 	genConfigCmd.Flags().StringArrayVar(&genConfigCmdFlags.configPatchWorker, "config-patch-worker", nil, "patch generated machineconfigs (applied to 'worker' type)")
 	genConfigCmd.Flags().StringSliceVar(&genConfigCmdFlags.registryMirrors, "registry-mirror", []string{}, "list of registry mirrors to use in format: <registry host>=<mirror URL>")
 	genConfigCmd.Flags().BoolVarP(&genConfigCmdFlags.persistConfig, "persist", "p", true, "the desired persist value for configs")
-	genConfigCmd.Flags().BoolVarP(&genConfigCmdFlags.withExamples, "with-examples", "", true, "renders all machine configs with the commented examples")
-	genConfigCmd.Flags().BoolVarP(&genConfigCmdFlags.withDocs, "with-docs", "", true, "renders all machine configs adding the documentation for each field")
 	genConfigCmd.Flags().BoolVarP(&genConfigCmdFlags.withClusterDiscovery, "with-cluster-discovery", "", true, "enable cluster discovery feature")
 	genConfigCmd.Flags().BoolVarP(&genConfigCmdFlags.withKubeSpan, "with-kubespan", "", false, "enable KubeSpan feature")
 	genConfigCmd.Flags().StringVar(&genConfigCmdFlags.withSecrets, "with-secrets", "", "use a secrets file generated using 'gen secrets'")

pkg/machinery/config/config.go

@@ -5,8 +5,6 @@
 // Package config provides methods to generate and consume Talos configuration.
 package config
 
-//go:generate docgen -generate-schema-from-dir types/ -json-schema-output schemas/config.schema.json -version-tag-file ../gendata/data/tag
-
 import "github.com/siderolabs/talos/pkg/machinery/config/config"
 
 // Config defines the interface to access contents of the machine configuration.

pkg/machinery/config/types/network/default_action_config.go

@@ -35,19 +35,11 @@ var (
 
 // DefaultActionConfigV1Alpha1 is a ingress firewall default action configuration document.
 //
-//	examples:
-//	  - value: exampleDefaultActionConfigV1Alpha1()
-//	alias: NetworkDefaultActionConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/NetworkDefaultActionConfig
+// docgen:configuration
 type DefaultActionConfigV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Default action for all not explicitly configured ingress traffic: accept or block.
-	//   values:
-	//     - "accept"
-	//     - "block"
-	Ingress nethelpers.DefaultAction `yaml:"ingress"`
+	// The default action for all configured ingress traffic not explicitly defined.
+	Ingress nethelpers.DefaultAction `yaml:"ingress" docgen:"{'in': '1.7', 'values': ['accept', 'block']}"`
 }
 
 // NewDefaultActionConfigV1Alpha1 creates a new DefaultActionConfig config document.

pkg/machinery/config/types/network/network.go

@@ -5,6 +5,4 @@
 // Package network provides network machine configuration documents.
 package network
 
-//go:generate docgen -output network_doc.go network.go default_action_config.go port_range.go rule_config.go
-
 //go:generate deep-copy -type DefaultActionConfigV1Alpha1 -type RuleConfigV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go .

pkg/machinery/config/types/network/rule_config.go

@@ -45,50 +45,25 @@ var (
 
 // RuleConfigV1Alpha1 is a network firewall rule config document.
 //
-//	examples:
-//	  - value: exampleRuleConfigV1Alpha1()
-//	alias: NetworkRuleConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/NetworkRuleConfig
+// docgen:configuration
 type RuleConfigV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Name of the config document.
-	//   schemaRequired: true
-	MetaName string `yaml:"name"`
-	//   description: |
-	//     Port selector defines which ports and protocols on the host are affected by the rule.
-	PortSelector RulePortSelector `yaml:"portSelector"`
-	//   description: |
-	//     Ingress defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`.
-	Ingress IngressConfig `yaml:"ingress" merge:"replace"`
+	// Name of the config document.
+	MetaName string `yaml:"name" docgen:"{'in': '1.7', 'optional': false}"`
+	// The port selector defines which ports and protocols on the host are affected by the rule.
+	PortSelector RulePortSelector `yaml:"portSelector" docgen:"{'in': '1.7'}"`
+	// Defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`.
+	Ingress IngressConfig `yaml:"ingress" merge:"replace" docgen:"{'in': '1.7'}"`
 }
 
 // RulePortSelector is a port selector for the network rule.
+//
+// docgen:configuration
 type RulePortSelector struct {
-	//   description: |
-	//     Ports defines a list of port ranges or single ports.
-	//     The port ranges are inclusive, and should not overlap.
-	//   examples:
-	//    - value: >
-	//       examplePortRanges1()
-	//    - value: >
-	//       examplePortRanges2()
-	//   schema:
-	//     type: array
-	//     items:
-	//       oneOf:
-	//         - type: integer
-	//         - type: string
-	Ports PortRanges `yaml:"ports" merge:"replace"`
-	//   description: |
-	//     Protocol defines traffic protocol (e.g. TCP or UDP).
-	//   values:
-	//    - "tcp"
-	//    - "udp"
-	//    - "icmp"
-	//    - "icmpv6"
-	Protocol nethelpers.Protocol `yaml:"protocol"`
+	// Defines a list of port ranges or single ports. The port ranges are inclusive, and should not overlap.
+	Ports PortRanges `yaml:"ports" merge:"replace" docgen:"{'in': '1.7'}"`
+	// Defines traffic protocol (e.g. TCP or UDP).
+	Protocol nethelpers.Protocol `yaml:"protocol" docgen:"{'in': '1.7', 'values': ['tcp', 'udp', 'icmp', 'icmpv6']}"`
 }
 
 // IngressConfig is a ingress config.
@@ -97,26 +72,17 @@ type RulePortSelector struct {
 type IngressConfig []IngressRule
 
 // IngressRule is a ingress rule.
+//
+// docgen:configuration
 type IngressRule struct {
-	//   description: |
-	//     Subnet defines a source subnet.
-	//   examples:
-	//    - value: >
-	//       netip.MustParsePrefix("10.3.4.0/24")
-	//    - value: >
-	//       netip.MustParsePrefix("2001:db8::/32")
-	//    - value: >
-	//       netip.MustParsePrefix("1.3.4.5/32")
-	//   schema:
-	//     type: string
-	//     pattern: ^[0-9a-f.:]+/\d{1,3}$
-	Subnet netip.Prefix `yaml:"subnet"`
+	// Defines a source subnet.
+	Subnet netip.Prefix `yaml:"subnet" docgen:"{'in': '1.7', 'pattern': '^[0-9a-f.:]+/\d{1,3}$'}"`
 	//   description: |
 	//     Except defines a source subnet to exclude from the rule, it gets excluded from the `subnet`.
 	//   schema:
 	//     type: string
 	//     pattern: ^[0-9a-f.:]+/\d{1,3}$
-	Except Prefix `yaml:"except,omitempty"`
+	Except Prefix `yaml:"except,omitempty" docgen:"{'in': '1.7', 'pattern': '^[0-9a-f.:]+/\d{1,3}$'}"`
 }
 
 // Prefix is a wrapper for netip.Prefix.

pkg/machinery/config/types/runtime/event_sink.go

@@ -41,19 +41,11 @@ var (
 
 // EventSinkV1Alpha1 is a event sink config document.
 //
-//	examples:
-//	  - value: exampleEventSinkV1Alpha1()
-//	alias: EventSinkConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/EventSinkConfig
+// docgen:configuration
 type EventSinkV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     The endpoint for the event sink as 'host:port'.
-	//   examples:
-	//     - value: >
-	//        "10.3.7.3:2810"
-	Endpoint string `yaml:"endpoint"`
+	// The endpoint for the event sink as 'host:port'.
+	Endpoint string `yaml:"endpoint" docgen:"{'in': '1.7'}"`
 }
 
 // NewEventSinkV1Alpha1 creates a new eventsink config document.

pkg/machinery/config/types/runtime/extensions/extensions.go

@@ -5,6 +5,4 @@
 // Package extensions provides extensions config documents.
 package extensions
 
-//go:generate docgen -output extensions_doc.go extensions.go service_config.go
-
 //go:generate deep-copy -type ServiceConfigV1Alpha1 -pointer-receiver -header-file ../../../../../../hack/boilerplate.txt -o deep_copy.generated.go .

pkg/machinery/config/types/runtime/extensions/service_config.go

@@ -40,33 +40,25 @@ var (
 
 // ServiceConfigV1Alpha1 is a extensionserviceconfig document.
 //
-//	examples:
-//	  - value: extensionServiceConfigV1Alpha1()
-//	alias: ExtensionServiceConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/ExtensionServiceConfig
+//docgen:configuration
 type ServiceConfigV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Name of the extension service.
-	//   schemaRequired: true
-	ServiceName string `yaml:"name"`
-	//   description: |
-	//     The config files for the extension service.
-	ServiceConfigFiles []ConfigFile `yaml:"configFiles,omitempty"`
-	//   description: |
-	//     The environment for the extension service.
-	ServiceEnvironment []string `yaml:"environment,omitempty"`
+	// The name of the extension service.
+	ServiceName string `yaml:"name" docgen:"{'in': '1.7', 'optional': false}"`
+	// The config files for the extension service.
+	ServiceConfigFiles []ConfigFile `yaml:"configFiles,omitempty" docgen:"{'in': '1.7'}"`
+	// The environment for the extension service.
+	ServiceEnvironment []string `yaml:"environment,omitempty" docgen:"{'in': '1.7'}"`
 }
 
 // ConfigFile is a config file for extension services.
+//
+//docgen:configuration
 type ConfigFile struct {
-	//   description: |
-	//     The content of the extension service config file.
-	ConfigFileContent string `yaml:"content"`
-	//   description: |
-	//     The mount path of the extension service config file.
-	ConfigFileMountPath string `yaml:"mountPath"`
+	// The content of the extension service config file.
+	ConfigFileContent string `yaml:"content" docgen:"{'in': '1.7'}"`
+	// The mount path of the extension service config file.
+	ConfigFileMountPath string `yaml:"mountPath" docgen:"{'in': '1.7'}"`
 }
 
 // NewServicesConfigV1Alpha1 creates a new siderolink config document.

pkg/machinery/config/types/runtime/kmsg_log.go

@@ -46,23 +46,14 @@ var (
 //	alias: KmsgLogConfig
 //	schemaRoot: true
 //	schemaMeta: v1alpha1/KmsgLogConfig
+//
+// docgen:configuration
 type KmsgLogV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Name of the config document.
-	MetaName string `yaml:"name"`
-	//   description: |
-	//     The URL encodes the log destination.
-	//     The scheme must be tcp:// or udp://.
-	//     The path must be empty.
-	//     The port is required.
-	//   examples:
-	//     - value: >
-	//        "udp://10.3.7.3:2810"
-	//   schema:
-	//     type: string
-	//     pattern: "^(tcp|udp)://"
-	KmsgLogURL meta.URL `yaml:"url"`
+	// Name of the config document.
+	MetaName string `yaml:"name" docgen:"{'in': '1.7'}"`
+	// Encodes the log destination. The path must be empty and the port is required.
+	KmsgLogURL meta.URL `yaml:"url" docgen:"{'in': '1.7', 'pattern': '^(tcp|udp)://'}"`
 }
 
 // NewKmsgLogV1Alpha1 creates a new eventsink config document.

pkg/machinery/config/types/runtime/runtime.go

@@ -5,6 +5,4 @@
 // Package runtime provides runtime machine configuration documents.
 package runtime
 
-//go:generate docgen -output runtime_doc.go runtime.go kmsg_log.go event_sink.go watchdog_timer.go
-
 //go:generate deep-copy -type EventSinkV1Alpha1 -type KmsgLogV1Alpha1 -type WatchdogTimerV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go .

pkg/machinery/config/types/runtime/watchdog_timer.go

@@ -45,29 +45,13 @@ const (
 
 // WatchdogTimerV1Alpha1 is a watchdog timer config document.
 //
-//	examples:
-//	  - value: exampleWatchdogTimerV1Alpha1()
-//	alias: WatchdogTimerConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/WatchdogTimerConfig
+// docgen:configuration
 type WatchdogTimerV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Path to the watchdog device.
-	//   examples:
-	//     - value: >
-	//        "/dev/watchdog0"
-	WatchdogDevice string `yaml:"device"`
-	//   description: |
-	//     Timeout for the watchdog.
-	//
-	//     If Talos is unresponsive for this duration, the watchdog will reset the system.
-	//
-	//     Default value is 1 minute, minimum value is 10 seconds.
-	//   schema:
-	//     type: string
-	//     pattern: ^[-+]?(((\d+(\.\d*)?|\d*(\.\d+)+)([nuµm]?s|m|h))|0)+$
-	WatchdogTimeout time.Duration `yaml:"timeout,omitempty"`
+	// The Path to the watchdog device.
+	WatchdogDevice string `yaml:"device" docgen:"{'in': '1.7'}"`
+	// The timeout for the watchdog. If Talos is unresponsive for this duration, the watchdog will reset the system.
+	WatchdogTimeout time.Duration `yaml:"timeout,omitempty" docgen:"{'in': '1.7', 'default': '1m', 'pattern': '^[-+]?(((\d+(\.\d*)?|\d*(\.\d+)+)([nuµm]?s|m|h))|0)+$'}"`
 }
 
 // NewWatchdogTimerV1Alpha1 creates a new eventsink config document.

pkg/machinery/config/types/siderolink/siderolink.go

@@ -19,8 +19,6 @@ import (
 	"github.com/siderolabs/talos/pkg/machinery/config/validation"
 )
 
-//go:generate docgen -output ./siderolink_doc.go ./siderolink.go
-
 //go:generate deep-copy -type ConfigV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go .
 
 // Kind is a siderolink config document kind.
@@ -46,22 +44,11 @@ var (
 
 // ConfigV1Alpha1 is a SideroLink connection machine configuration document.
 //
-//	examples:
-//	  - value: exampleConfigV1Alpha1()
-//	alias: SideroLinkConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/SideroLinkConfig
+// docgen:configuration
 type ConfigV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     SideroLink API URL to connect to.
-	//   examples:
-	//     - value: >
-	//        "https://siderolink.api/join?token=secret"
-	//   schema:
-	//     type: string
-	//     pattern: "^(https|grpc)://"
-	APIUrlConfig meta.URL `yaml:"apiUrl"`
+	// The SideroLink API URL to connect to.
+	APIUrlConfig meta.URL `yaml:"apiUrl" docgen:"{'in': '1.7', 'pattern': '^(https|grpc)://'}"`
 }
 
 // NewConfigV1Alpha1 creates a new siderolink config document.