From 29136e17d42988adce479fc7b32d125213921b02 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Wed, 3 Dec 2025 19:11:23 -0700 Subject: [PATCH] Recommended changes from review - Reorganized documentation - Reordered columns - Renamed column names - Added `--` to options in output - Updated aliases Signed-off-by: Jonathon Anderson --- internal/app/wwctl/overlay/info/main.go | 10 ++-- internal/app/wwctl/overlay/info/main_test.go | 2 +- internal/app/wwctl/overlay/info/root.go | 2 +- userdocs/overlays/overlays.rst | 57 +++++++++++--------- userdocs/overlays/templates.rst | 22 ++++++++ 5 files changed, 61 insertions(+), 32 deletions(-) diff --git a/internal/app/wwctl/overlay/info/main.go b/internal/app/wwctl/overlay/info/main.go index a531e18a..50f0fe72 100644 --- a/internal/app/wwctl/overlay/info/main.go +++ b/internal/app/wwctl/overlay/info/main.go @@ -39,7 +39,7 @@ func CobraRunE(cmd *cobra.Command, args []string) error { } } t := table.New(cmd.OutOrStdout()) - t.AddHeader("OVERLAY VARIABLE", "HELP", "TYPE", "CMD OPTION") + t.AddHeader("VARIABLE", "OPTION", "TYPE", "HELP") for _, v := range vars { found := false @@ -78,19 +78,19 @@ func CobraRunE(cmd *cobra.Command, args []string) error { if match { opt := "" if val.LongOpt != "" { - opt = val.LongOpt + opt = "--" + val.LongOpt } if hasCommentHelp { - t.AddLine(v, helpText, val.Type, opt) + t.AddLine(v, opt, val.Type, helpText) } else { - t.AddLine(v, val.Comment, val.Type, opt) + t.AddLine(v, opt, val.Type, val.Comment) } found = true } } if !found { if hasCommentHelp { - t.AddLine(v, helpText, "", "") + t.AddLine(v, "", "", helpText) } else if strings.Contains(v, "Tags") { t.AddLine(v, "", "", "", "") } diff --git a/internal/app/wwctl/overlay/info/main_test.go b/internal/app/wwctl/overlay/info/main_test.go index 94c4ddbd..e10b78b0 100644 --- a/internal/app/wwctl/overlay/info/main_test.go +++ b/internal/app/wwctl/overlay/info/main_test.go @@ -39,7 +39,7 @@ func Test_Overlay_Variables(t *testing.T) { assert.NoError(t, err) output := buf.String() - assert.Contains(t, output, "OVERLAY VARIABLE") + assert.Contains(t, output, "VARIABLE") assert.Contains(t, output, ".Kernel.Tags.foo") assert.Contains(t, output, "some help text") assert.Regexp(t, `(?s)First Line.*Second Line`, output, "First Line should come before Second Line") diff --git a/internal/app/wwctl/overlay/info/root.go b/internal/app/wwctl/overlay/info/root.go index 8cfa3024..eee3f4b8 100644 --- a/internal/app/wwctl/overlay/info/root.go +++ b/internal/app/wwctl/overlay/info/root.go @@ -10,7 +10,7 @@ var ( Use: "info [flags] OVERLAY_NAME FILE_PATH", Short: "Show variables for a template file in an overlay", Long: "This command will show the variables for a given template file in a given\n" + "overlay.", - Aliases: []string{"vars", "tags", "information"}, + Aliases: []string{"variables", "vars"}, Args: cobra.ExactArgs(2), RunE: CobraRunE, ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) { diff --git a/userdocs/overlays/overlays.rst b/userdocs/overlays/overlays.rst index 1382c99c..5d180db5 100644 --- a/userdocs/overlays/overlays.rst +++ b/userdocs/overlays/overlays.rst @@ -25,6 +25,37 @@ within the overlays with ``wwctl overlay list --all``. fstab etc/ false fstab etc/fstab.ww false +Overlay Variables +----------------- + +The command ``wwctl overlay info`` shows the variables used in an overlay +template, along with the help text for each variable. + +.. code-block:: console + + # wwctl overlay info NetworkManager etc/NetworkManager/system-connections/ww4-managed.ww + VARIABLE HELP TYPE OPTION + -------- ---- ---- ------ + $netdev.Device Set the device for given network string --netdev + $netdev.Gateway Set the node's network device gateway IP --gateway + $netdev.Hwaddr Set the device's HW address for given network string --hwaddr + $netdev.Ipaddr IPv4 address in given network IP --ipaddr + $netdev.Ipaddr6 IPv4 address in given network IP --ipaddr + $netdev.Ipaddr6 IPv6 address IP --ipaddr6 + $netdev.MTU Set the mtu string --mtu + $netdev.OnBoot.BoolDefaultTrue Enable/disable network device (true/false) WWbool --onboot + $netdev.Tags + $netdev.Tags.DNSSEARCH + $netdev.Tags.downdelay + $netdev.Tags.master + $netdev.Tags.miimon + $netdev.Tags.mode + $netdev.Tags.parent_device + $netdev.Tags.updelay + $netdev.Tags.vlan_id + $netdev.Tags.xmit_hash_policy + $netdev.Type Set device type of given network string --type + Structure ========= @@ -89,13 +120,10 @@ Creating and Modifying Overlays You can add a new overlay to Warewulf with ``wwctl overlay create``. - - .. code-block:: shell wwctl overlay create issue - A new overlay is just an empty directory. For it to be useful it needs to contain some files. @@ -106,14 +134,11 @@ into the overlay. wwctl overlay import --parents issue /etc/issue - - This imports ``/etc/issue`` from the Warewulf server into the new ``issue`` overlay. .. note:: - The ``issue`` overlay already existed as a distribution overlay. Creating one shadows the distribution overlay with a new site overlay, allowing for local modification. @@ -124,12 +149,10 @@ overlay. You can also edit a new or existing overlay file in an interactive editor. - .. code-block:: shell wwctl overlay edit issue /etc/issue - Use ``wwctl overlay show`` to inspect the content of an overlay file. .. code-block:: shell @@ -146,8 +169,6 @@ distribution to a given cluster node. wwctl overlay import issue /etc/issue /etc/issue.ww wwctl overlay show issue /etc/issue.ww --render=n1 - - More information about templates is available in :ref:`its own section `. @@ -161,20 +182,6 @@ option. It is not possible to delete files with an overlay. - -Overlay Variables ------------------ - -The command ``wwctl overlay variables`` can be used to show the used variables -in a template. The command also shows the help text for each variable. The help -text can be defined in two ways. The first is a general documentation which is -not tied to a variable. This can be done with the following syntax: -``{{/* wwdoc: Your documentation text */}}``. The second way is to define a help -text for a specific variable. This can be done with the following syntax: -``{{/* .My.Var: Your help text */}}``. If a help text is defined for a variable, -it will be used instead of the default help text. - - Permissions ----------- @@ -398,7 +405,7 @@ provided as an example. In particular, the provided `tstruct.md.ww` demonstrates the use of most available template metadata. .. code-block:: shell - + wwctl overlay show --render= debug tstruct.md.ww .. _localtime: diff --git a/userdocs/overlays/templates.rst b/userdocs/overlays/templates.rst index 683e8fc5..437a21c6 100644 --- a/userdocs/overlays/templates.rst +++ b/userdocs/overlays/templates.rst @@ -33,6 +33,28 @@ non-overlay templates as well. commands for the ``wwctl power``, ``wwctl sensor``, and ``wwctl console`` commands. +Template documentation +====================== + +Templates can include documentation to be included in the output of ``wwctl overlay info``. + +.. code:: + + {{/* wwdoc: Your documentation text */}} + +Template variables +================== + +Overlay templates have access to a number of variables that provide information +about the server configuration, the node being provisioned, and all nodes in the +cluster. An example of the variables available, and their use, is included with +Warewulf in the ``tstruct.ww`` template of the ``debug`` overlay. + +Variables used in an overlay template can be documented by adding a comment to +the template with the form ``{{/* .My.Var: Your help text */}}``. Variable help +text defined in a comment replaces that variable's default help text in the +output of ``wwctl overlay info``. + Template functions ==================