diff --git a/internal/app/wwctl/overlay/variables/main.go b/internal/app/wwctl/overlay/variables/main.go index f73e6617..55fc3ec2 100644 --- a/internal/app/wwctl/overlay/variables/main.go +++ b/internal/app/wwctl/overlay/variables/main.go @@ -10,6 +10,7 @@ import ( "github.com/warewulf/warewulf/internal/pkg/node" "github.com/warewulf/warewulf/internal/pkg/overlay" "github.com/warewulf/warewulf/internal/pkg/wwlog" + "golang.org/x/exp/maps" ) func CobraRunE(cmd *cobra.Command, args []string) error { @@ -30,6 +31,13 @@ func CobraRunE(cmd *cobra.Command, args []string) error { if vars == nil { return fmt.Errorf("could not parse variables for %s in overlay %s", filePath, overlayName) } + commentKeys := maps.Keys(commentMap) + sort.Strings(commentKeys) + for _, docLn := range commentKeys { + if strings.Contains(docLn, "wwdoc") { + wwlog.Info(commentMap[docLn]) + } + } t := table.New(cmd.OutOrStdout()) t.AddHeader("OVERLAY VARIABLE", "HELP", "TYPE", "CMD OPTION") diff --git a/internal/app/wwctl/overlay/variables/main_test.go b/internal/app/wwctl/overlay/variables/main_test.go index 1b462216..fc339a82 100644 --- a/internal/app/wwctl/overlay/variables/main_test.go +++ b/internal/app/wwctl/overlay/variables/main_test.go @@ -13,10 +13,13 @@ import ( func Test_Overlay_Variables(t *testing.T) { env := testenv.New(t) defer env.RemoveAll() + wwlog.SetLogLevel(wwlog.DEBUG) warewulfd.SetNoDaemon() templateContent := ` {{/* .Kernel.Tags.foo: "some help text" */}} +{{/* wwdoc1: First Line */}} +{{/* wwdoc2: Second Line */}} {{ .Kernel.Tags.foo }} {{ .Node.Tags.bar }} {{ .Cluster.Tags.baz }} @@ -39,6 +42,7 @@ func Test_Overlay_Variables(t *testing.T) { assert.Contains(t, output, "OVERLAY 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") }) t.Run("overlay variables no file", func(t *testing.T) { diff --git a/internal/pkg/overlay/overlay.go b/internal/pkg/overlay/overlay.go index deee0ba3..100f3d18 100644 --- a/internal/pkg/overlay/overlay.go +++ b/internal/pkg/overlay/overlay.go @@ -16,7 +16,6 @@ import ( "github.com/Masterminds/sprig/v3" "github.com/coreos/go-systemd/v22/unit" - "gopkg.in/yaml.v2" "github.com/warewulf/warewulf/internal/pkg/config" "github.com/warewulf/warewulf/internal/pkg/node" @@ -312,7 +311,8 @@ func (overlay Overlay) ParseVars(file string) []string { // ParseCommentVars parses a template file for comments that contain variable documentations. // The comments must be in the format `{{/* key: value */}}`. The content is parsed as YAML. -func (overlay Overlay) ParseCommentVars(file string) map[string]string { +func (overlay Overlay) ParseCommentVars(file string) (retMap map[string]string) { + retMap = make(map[string]string) if !strings.HasSuffix(file, ".ww") { return nil } @@ -328,24 +328,15 @@ func (overlay Overlay) ParseCommentVars(file string) map[string]string { return nil } - vars := make(map[string]string) - re := regexp.MustCompile(`{{\s*/\*(.*?)\*/\s*}}`) + re := regexp.MustCompile(`{{\s*/\*\s*(.*?):\s*(.*?)\s*\*/\s*}}`) matches := re.FindAllStringSubmatch(string(content), -1) - - for _, match := range matches { - commentContent := strings.TrimSpace(match[1]) - var data map[string]string - err := yaml.Unmarshal([]byte(commentContent), &data) - if err == nil { - for k, v := range data { - vars[k] = v - } - } else { - wwlog.Debug("Could not parse template comment as yaml in file %s: %s", file, err) + wwlog.Debug("matches: %v len(%d:%d)", matches, len(matches), len(matches[0])) + for i := range matches { + if len(matches[i]) > 2 { + retMap[matches[i][1]] = matches[i][2] } } - - return vars + return } // walkParseTree recursively traverses the template's parse tree to find variables. diff --git a/userdocs/overlays/overlays.rst b/userdocs/overlays/overlays.rst index a12c48e0..1382c99c 100644 --- a/userdocs/overlays/overlays.rst +++ b/userdocs/overlays/overlays.rst @@ -89,10 +89,13 @@ 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. @@ -103,11 +106,14 @@ 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. @@ -118,10 +124,12 @@ 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 @@ -138,6 +146,8 @@ 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 `. @@ -151,6 +161,20 @@ 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 ----------- @@ -163,6 +187,7 @@ mode that they have on the Warewulf server. Use ``wwctl overlay chown`` and wwctl overlay chown issue /etc/issue.ww root root wwctl overlay chmod issue /etc/issue.ww 0644 + Distribution Overlays =====================