Skip to content

Commit 86c94ef

Browse files
committed
refactor: docgen and config examples
Short version is: move from global variables/`init()` function into explicit functions. `docgen` was updated to skip creating any top-level global variables, now `Doc` information is generated on the fly when it is accessed. Talos itself doesn't marshal the configuration often, so in general it should never be accessed for Talos (but will be accessed e.g. for `talosctl`). Machine config examples were changed manually from variables to functions returning a value and moved to a separate file. There are no changes to the output of `talosctl gen config`. There is a small change to the generated documentation, which I believe is a correct one, as previously due to value reuse it was clobbered with other data. Signed-off-by: Andrey Smirnov <andrey.smirnov@siderolabs.com>
1 parent ee6d639 commit 86c94ef

File tree

6 files changed

+4808
-3971
lines changed

6 files changed

+4808
-3971
lines changed

hack/docgen/main.go

Lines changed: 56 additions & 48 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

internal/pkg/tui/installer/state.go

Lines changed: 26 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ import (
1717
"github.com/siderolabs/talos/internal/pkg/tui/components"
1818
"github.com/siderolabs/talos/pkg/images"
1919
machineapi "github.com/siderolabs/talos/pkg/machinery/api/machine"
20+
"github.com/siderolabs/talos/pkg/machinery/config/encoder"
2021
"github.com/siderolabs/talos/pkg/machinery/config/machine"
2122
"github.com/siderolabs/talos/pkg/machinery/config/types/v1alpha1"
2223
"github.com/siderolabs/talos/pkg/machinery/constants"
@@ -103,12 +104,12 @@ func NewState(ctx context.Context, installer *Installer, conn *Connection) (*Sta
103104
networkConfigItems := []*components.Item{
104105
components.NewItem(
105106
"Hostname",
106-
v1alpha1.NetworkConfigDoc.Describe("hostname", true),
107+
describe[v1alpha1.NetworkConfig]("hostname", true),
107108
&opts.MachineConfig.NetworkConfig.Hostname,
108109
),
109110
components.NewItem(
110111
"DNS Domain",
111-
v1alpha1.ClusterNetworkConfigDoc.Describe("dnsDomain", true),
112+
describe[v1alpha1.ClusterNetworkConfig]("dnsDomain", true),
112113
&opts.ClusterConfig.ClusterNetwork.DnsDomain,
113114
),
114115
}
@@ -148,10 +149,10 @@ func NewState(ctx context.Context, installer *Installer, conn *Connection) (*Sta
148149

149150
if !conn.ExpandingCluster() {
150151
networkConfigItems = append(networkConfigItems,
151-
components.NewSeparator(v1alpha1.ClusterNetworkConfigDoc.Describe("cni", true)),
152+
components.NewSeparator(describe[v1alpha1.ClusterNetworkConfig]("cni", true)),
152153
components.NewItem(
153154
"Type",
154-
v1alpha1.ClusterNetworkConfigDoc.Describe("cni", true),
155+
describe[v1alpha1.ClusterNetworkConfig]("cni", true),
155156
&state.cni,
156157
components.NewTableHeaders("CNI", "description"),
157158
constants.FlannelCNI, "CNI used by Talos by default",
@@ -164,11 +165,11 @@ func NewState(ctx context.Context, installer *Installer, conn *Connection) (*Sta
164165
NewPage("Installer Params",
165166
components.NewItem(
166167
"Image",
167-
v1alpha1.InstallConfigDoc.Describe("image", true),
168+
describe[v1alpha1.InstallConfig]("image", true),
168169
&opts.MachineConfig.InstallConfig.InstallImage,
169170
),
170171
components.NewSeparator(
171-
v1alpha1.InstallConfigDoc.Describe("disk", true),
172+
describe[v1alpha1.InstallConfig]("disk", true),
172173
),
173174
components.NewItem(
174175
"Install Disk",
@@ -180,18 +181,18 @@ func NewState(ctx context.Context, installer *Installer, conn *Connection) (*Sta
180181
NewPage("Machine Config",
181182
components.NewItem(
182183
"Machine Type",
183-
v1alpha1.MachineConfigDoc.Describe("type", true),
184+
describe[v1alpha1.MachineConfig]("type", true),
184185
&opts.MachineConfig.Type,
185186
machineTypes...,
186187
),
187188
components.NewItem(
188189
"Cluster Name",
189-
v1alpha1.ClusterConfigDoc.Describe("clusterName", true),
190+
describe[v1alpha1.ClusterConfig]("clusterName", true),
190191
&opts.ClusterConfig.Name,
191192
),
192193
components.NewItem(
193194
"Control Plane Endpoint",
194-
v1alpha1.ControlPlaneConfigDoc.Describe("endpoint", true),
195+
describe[v1alpha1.ControlPlaneConfig]("endpoint", true),
195196
&opts.ClusterConfig.ControlPlane.Endpoint,
196197
),
197198
components.NewItem(
@@ -201,7 +202,7 @@ func NewState(ctx context.Context, installer *Installer, conn *Connection) (*Sta
201202
),
202203
components.NewItem(
203204
"Allow Scheduling on Control Planes",
204-
v1alpha1.ClusterConfigDoc.Describe("allowSchedulingOnControlPlanes", true),
205+
describe[v1alpha1.ClusterConfig]("allowSchedulingOnControlPlanes", true),
205206
&opts.ClusterConfig.AllowSchedulingOnControlPlanes,
206207
),
207208
),
@@ -268,27 +269,27 @@ func configureAdapter(installer *Installer, opts *machineapi.GenerateConfigurati
268269
items := []*components.Item{
269270
components.NewItem(
270271
"Use DHCP",
271-
v1alpha1.DeviceDoc.Describe("dhcp", true),
272+
describe[v1alpha1.Device]("dhcp", true),
272273
&adapterSettings.Dhcp,
273274
),
274275
components.NewItem(
275276
"Ignore",
276-
v1alpha1.DeviceDoc.Describe("ignore", true),
277+
describe[v1alpha1.Device]("ignore", true),
277278
&adapterSettings.Ignore,
278279
),
279280
components.NewItem(
280281
"CIDR",
281-
v1alpha1.DeviceDoc.Describe("cidr", true),
282+
describe[v1alpha1.Device]("cidr", true),
282283
&adapterSettings.Cidr,
283284
),
284285
components.NewItem(
285286
"MTU",
286-
v1alpha1.DeviceDoc.Describe("mtu", true),
287+
describe[v1alpha1.Device]("mtu", true),
287288
&adapterSettings.Mtu,
288289
),
289290
components.NewItem(
290291
"Route Metric",
291-
v1alpha1.DeviceDoc.Describe("dhcpOptions", true),
292+
describe[v1alpha1.Device]("dhcpOptions", true),
292293
&adapterSettings.DhcpOptions.RouteMetric,
293294
),
294295
}
@@ -339,3 +340,13 @@ func configureAdapter(installer *Installer, opts *machineapi.GenerateConfigurati
339340
})
340341
}
341342
}
343+
344+
type documentable interface {
345+
Doc() *encoder.Doc
346+
}
347+
348+
func describe[T documentable](field string, short bool) string {
349+
var zeroT T
350+
351+
return zeroT.Doc().Describe(field, short)
352+
}

0 commit comments

Comments
 (0)