Document template functions

- Closes: #698

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

internal/pkg/overlay/funcmap.go

@@ -16,10 +16,8 @@ import (
 	"github.com/warewulf/warewulf/internal/pkg/wwlog"
 )
 
-/*
-Reads a file file from the host fs. If the file has nor '/' prefix
-the path is relative to Paths.SysconfdirTemplates in the file are no evaluated.
-*/
+// Reads a file file from the host fs. If the file has nor '/' prefix the path
+// is relative to Paths.Sysconfdir. Templates in the file are no evaluated.
 func templateFileInclude(inc string) string {
 	conf := warewulfconf.Get()
 	if !strings.HasPrefix(inc, "/") {
@@ -33,11 +31,9 @@ func templateFileInclude(inc string) string {
 	return strings.TrimSuffix(string(content), "\n")
 }
 
-/*
-Reads a file into template the abort string is found in a line. First argument
-is the file to read, the second the abort string
-Templates in the file are no evaluated.
-*/
+// Reads a file into template the abort string is found in a line. First
+// argument is the file to read, the second the abort string. Templates in the
+// file are no evaluated.
 func templateFileBlock(inc string, abortStr string) (string, error) {
 	conf := warewulfconf.Get()
 	if !strings.HasPrefix(inc, "/") {
@@ -72,10 +68,7 @@ func templateFileBlock(inc string, abortStr string) (string, error) {
 
 }
 
-/*
-Reads a file relative to given image.
-Templates in the file are no evaluated.
-*/
+// Reads a file relative to given image. Templates in the file are not evaluated.
 func templateImageFileInclude(imagename string, filepath string) string {
 	wwlog.Verbose("Including file from Image into template: %s:%s", imagename, filepath)
 
@@ -106,8 +99,8 @@ func templateImageFileInclude(imagename string, filepath string) string {
 	return strings.TrimSuffix(string(content), "\n")
 }
 
-// don't return an error as we use this function for template evaluation,
-// so error will turn up there as the return string
+// Don't return an error as we use this function for template evaluation, so
+// error will turn up there as the return string
 func createIgnitionJson(node *node.Node) string {
 	conf, rep, err := node.GetConfig()
 	if len(conf.Storage.Disks) == 0 && len(conf.Storage.Filesystems) == 0 {

userdocs/contents/overlays.rst

@@ -240,6 +240,125 @@ attributes.
    will be dropped, so ``/etc/hosts.ww`` will end up being
    ``/etc/hosts``.
 
+Template functions
+==================
+
+Warewulf templates have access to a number of functions.
+
+In addition to the custom functions below, the `sprig functions`_ are also
+available.
+
+.. _sprig functions: https://masterminds.github.io/sprig/
+
+Include
+-------
+
+Reads content from the given file into the template. If the file does not begin
+with ``/`` it is considered relative to ``Paths.Sysconfdir``.
+
+.. code-block:: plaintext
+
+   {{ Include "/root/.ssh/authorized_keys" }}
+
+IncludeFrom
+-----------
+
+Reads content from the given file from the given image into the template.
+
+.. code-block:: plaintext
+
+   {{ IncludeFrom $.ImageName "/etc/passwd" }}
+
+IncludeBlock
+------------
+
+Reads content from the given file into the template, stopping when the provided
+abort string is found.
+
+.. code-block:: plaintext
+  
+   {{ IncludeBlock "/etc/hosts" "# Do not edit after this line" }}
+
+ImportLink
+----------
+
+Causes the processed template file to becoma a symlink to the same target as the
+referenced symlink.
+
+.. code-block:: plaintext
+
+   {{ ImportLink "/etc/localtime" }}
+
+basename
+--------
+
+Returns the base name of the given path.
+
+.. code-block:: plaintext
+
+   {{- range $type, $name := $.Tftp.IpxeBinaries }}
+    if option architecture-type = {{ $type }} {
+        filename "/warewulf/{{ basename $name }}";
+    }
+   {{- end }}
+
+file
+----
+
+Write the content from the template to the specified file name. May be specified
+more than once in a template to write content to multiple files.
+
+.. code-block:: plaintext
+
+   {{- range $devname, $netdev := .NetDevs }}
+   {{- $filename := print "ifcfg-" $devname ".conf" }}
+   {{- file $filename }}
+   {{/* content here */}}
+   {{- end }}
+
+softlink
+--------
+
+Causes the processed template file to become a symlink to the referenced target.
+
+.. code-block:: plaintext
+  
+   {{ printf "%s/%s" "/usr/share/zoneinfo" .Tags.localtime | softlink }}
+
+readlink
+--------
+
+Equivalent to ``filepath.EvalSymlinks``. Returns the target path of a named
+symlink.
+
+.. code-block:: plaintext
+
+   {{ readlink /etc/localtime }}
+
+IgnitionJson
+------------
+
+Generates JSON suitable for use by Ignition to create 
+
+abort
+-----
+
+Immediately aborts processing the template and does not write a file.
+
+.. code-block::
+  
+   {{ abort }}
+
+nobackup
+--------
+
+   Disables the creation of a backup file when replacing files with the current
+   template.
+
+.. code-block::
+
+   {{ nobackup }}
+
 Managing overlays
 =================