add more generic documentation via wwdoc(n)

doc

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

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

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.

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
 <templates>`.
 
@@ -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
 =====================