Recommended changes from review

- Reorganized documentation
- Reordered columns
- Renamed column names
- Added `--` to options in output
- Updated aliases

Signed-off-by: Jonathon Anderson <janderson@ciq.com>

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, "", "", "", "")
 			}

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")

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) {

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
 <templates>`.
 
@@ -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=<nodename> debug tstruct.md.ww
 
 .. _localtime:

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
 ==================