docs: rework machine config documentation generation

Generate a structured table of contents following the structure of the
config.

Make high-level examples follow the full structure of the config.

Document new multi-doc machine config.

Fixes #8023

Signed-off-by: Andrey Smirnov <andrey.smirnov@siderolabs.com>

Dockerfile

@@ -969,7 +969,7 @@ ARG TARGETOS
 ARG TARGETARCH
 WORKDIR /src
 COPY --from=talosctl-targetarch /talosctl-${TARGETOS}-${TARGETARCH} /bin/talosctl
-RUN env HOME=/home/user TAG=latest /bin/talosctl docs --config /tmp \
+RUN env HOME=/home/user TAG=latest /bin/talosctl docs --config /tmp/configuration \
     && env HOME=/home/user TAG=latest /bin/talosctl docs --cli /tmp
 COPY ./pkg/machinery/config/types/v1alpha1/schemas/ /tmp/schemas/
 
@@ -998,7 +998,7 @@ RUN protoc \
     /protos/time/*.proto
 
 FROM scratch AS docs
-COPY --from=docs-build /tmp/configuration.md /website/content/v1.6/reference/
+COPY --from=docs-build /tmp/configuration/ /website/content/v1.6/reference/configuration/
 COPY --from=docs-build /tmp/cli.md /website/content/v1.6/reference/
 COPY --from=docs-build /tmp/schemas /website/content/v1.6/schemas/
 COPY --from=proto-docs-build /tmp/api.md /website/content/v1.6/reference/

cmd/talosctl/cmd/docs.go

@@ -16,19 +16,32 @@ import (
 
 	"github.com/spf13/cobra"
 	"github.com/spf13/cobra/doc"
+	"sigs.k8s.io/kustomize/kyaml/yaml"
 
+	"github.com/siderolabs/talos/pkg/machinery/config/encoder"
+	"github.com/siderolabs/talos/pkg/machinery/config/types/network"
+	"github.com/siderolabs/talos/pkg/machinery/config/types/runtime"
+	"github.com/siderolabs/talos/pkg/machinery/config/types/siderolink"
 	v1alpha1 "github.com/siderolabs/talos/pkg/machinery/config/types/v1alpha1"
 )
 
 func frontmatter(title, description string) string {
-	frontmatter := "---\n"
+	var buf bytes.Buffer
 
-	frontmatter += "title: " + title + "\n"
-	frontmatter += "desription: " + description + "\n"
+	buf.WriteString("---\n")
 
-	frontmatter += "---\n\n"
+	if err := yaml.NewEncoder(&buf).Encode(map[string]string{
+		"title":       title,
+		"description": description,
+	}); err != nil {
+		panic(err)
+	}
+
+	buf.WriteString("---\n")
+	buf.WriteString("\n")
+	buf.WriteString("<!-- markdownlint-disable -->\n\n")
 
-	return frontmatter + "<!-- markdownlint-disable -->\n\n"
+	return buf.String()
 }
 
 func linkHandler(name string) string {
@@ -39,10 +52,7 @@ func linkHandler(name string) string {
 	return "#" + strings.ToLower(base)
 }
 
-const (
-	cliDescription           = "Talosctl CLI tool reference."
-	configurationDescription = "Talos node configuration file reference."
-)
+const cliDescription = "Talosctl CLI tool reference."
 
 var (
 	cliDocs    bool
@@ -90,8 +100,36 @@ var docsCmd = &cobra.Command{
 		}
 
 		if configDocs || all {
-			if err := v1alpha1.GetConfigurationDoc().Write(dir, frontmatter("Configuration", configurationDescription)); err != nil {
-				return fmt.Errorf("failed to generate docs: %w", err)
+			for _, pkg := range []struct {
+				name    string
+				fileDoc *encoder.FileDoc
+			}{
+				{
+					name:    "network",
+					fileDoc: network.GetFileDoc(),
+				},
+				{
+					name:    "runtime",
+					fileDoc: runtime.GetFileDoc(),
+				},
+				{
+					name:    "siderolink",
+					fileDoc: siderolink.GetFileDoc(),
+				},
+				{
+					name:    "v1alpha1",
+					fileDoc: v1alpha1.GetFileDoc(),
+				},
+			} {
+				path := filepath.Join(dir, pkg.name)
+
+				if err := os.MkdirAll(path, 0o777); err != nil {
+					return fmt.Errorf("failed to create output directory %q", path)
+				}
+
+				if err := pkg.fileDoc.Write(path, frontmatter); err != nil {
+					return fmt.Errorf("failed to generate docs: %w", err)
+				}
 			}
 		}
 

cmd/talosctl/cmd/mgmt/cluster/internal/firewallpatch/firewallpatch.go

@@ -24,7 +24,7 @@ func ingressRuleWithinCluster(cidrs []netip.Prefix, gateways []netip.Addr) []net
 		rules = append(rules,
 			network.IngressRule{
 				Subnet: cidrs[i],
-				Except: netip.PrefixFrom(gateways[i], gateways[i].BitLen()),
+				Except: network.Prefix{Prefix: netip.PrefixFrom(gateways[i], gateways[i].BitLen())},
 			},
 		)
 	}

hack/docgen/main_test.go

@@ -15,6 +15,5 @@ func TestProcessFile(t *testing.T) {
 	outputFile := filepath.Join(t.TempDir(), "out.go")
 	schemaOutputFile := filepath.Join(t.TempDir(), "out.schema.json")
 	versionTagFile := filepath.Join("..", "..", "pkg", "machinery", "gendata", "data", "tag")
-	typeName := "Configuration"
-	processFile(inputFile, outputFile, schemaOutputFile, versionTagFile, typeName)
+	processFile([]string{inputFile}, outputFile, schemaOutputFile, versionTagFile)
 }

internal/app/machined/pkg/controllers/network/nftables_chain_config_test.go

@@ -41,7 +41,7 @@ func (suite *NfTablesChainConfigTestSuite) injectConfig(block bool) {
 	kubeletIngressCfg.Ingress = []networkcfg.IngressRule{
 		{
 			Subnet: netip.MustParsePrefix("10.0.0.0/8"),
-			Except: netip.MustParsePrefix("10.3.0.0/16"),
+			Except: networkcfg.Prefix{Prefix: netip.MustParsePrefix("10.3.0.0/16")},
 		},
 		{
 			Subnet: netip.MustParsePrefix("192.168.0.0/16"),