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 siderolabs#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,30 @@ 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/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 +50,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 +98,28 @@ 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:    "v1alpha1",
+					fileDoc: v1alpha1.GetFileDoc(),
+				},
+				{
+					name:    "siderolink",
+					fileDoc: siderolink.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)
+				}
 			}
 		}