From 82cdd1398723857fa5db440cb746b02d68efeec7 Mon Sep 17 00:00:00 2001
From: Jonathon Anderson <janderson@ciq.co>
Date: Thu, 20 Apr 2023 06:05:24 -0600
Subject: [PATCH] Documentation and tests for hostlist syntax

Added this to a new top-level page for wwctl

Closes #611

Signed-off-by: Jonathon Anderson <janderson@ciq.co>
---
 CHANGELOG.md                  |  4 ++++
 pkg/hostlist/hostlist_test.go | 37 +++++++++++++++++++++++++++++++++++
 userdocs/contents/wwctl.rst   | 33 +++++++++++++++++++++++++++++++
 userdocs/index.rst            |  1 +
 4 files changed, 75 insertions(+)
 create mode 100644 pkg/hostlist/hostlist_test.go
 create mode 100644 userdocs/contents/wwctl.rst

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 71dc96e8..2481d695 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- New documentation for the hostlist syntax. #611
+
 ### Fixed
 
 - The correct header is now displayed when `-al` flags are specified to overlay
diff --git a/pkg/hostlist/hostlist_test.go b/pkg/hostlist/hostlist_test.go
new file mode 100644
index 00000000..bd89d1ff
--- /dev/null
+++ b/pkg/hostlist/hostlist_test.go
@@ -0,0 +1,37 @@
+package hostlist
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+
+func Test_Single(t *testing.T) {
+	assert.Equal(t, []string{"node1"}, Expand([]string{"node1"}))
+}
+
+func Test_Multiple(t *testing.T) {
+	assert.Equal(t, []string{"node1", "node2"}, Expand([]string{"node1", "node2"}))
+}
+
+
+func Test_Range(t *testing.T) {
+	assert.Equal(t, []string{"node1", "node2"}, Expand([]string{"node[1-2]"}))
+}
+
+
+func Test_Internal_Comma(t *testing.T) {
+	assert.Equal(t, []string{"node1", "node2"}, Expand([]string{"node[1,2]"}))
+}
+
+func Test_Mixed_Range_Comma(t *testing.T) {
+	assert.Equal(t, []string{"node1", "node2", "node3"}, Expand([]string{"node[1,2-3]"}))
+}
+
+
+// not currently supported
+//
+// func Test_External_Comma(t *testing.T) {
+// 	assert.Equal(t, []string{"node1", "node2"}, Expand([]string{"node1,node2"}))
+// }
diff --git a/userdocs/contents/wwctl.rst b/userdocs/contents/wwctl.rst
new file mode 100644
index 00000000..5fa8ee48
--- /dev/null
+++ b/userdocs/contents/wwctl.rst
@@ -0,0 +1,33 @@
+============================
+Controlling Warewulf (wwctl)
+============================
+
+Warewulf's command-line interface is based primarily around the
+``wwctl`` command. This command has sub-commands for each major
+component of Warewulf's functionality.
+
+* ``configure`` configures external services that Warewulf depends on
+* ``container`` configures containers (node images)
+* ``kernel`` configures override kernels
+* ``node`` manages nodes in the cluster
+* ``profiles`` defines configuration which can be applied to multiple
+  nodes
+* ``overlays`` manages nodes
+* ``power`` turns nodes on and off
+* ``ssh`` provides basic parallel ssh functionality
+
+All of these subcommands (and their respective sub-subcommands) have
+built-in help with either ``wwctl help`` or ``--help``.
+
+Hostlists
+=========
+
+Many of the commands (e.g., ``wwctl node list`` support a "hostlist"
+syntax for referring to multiple nodes at once. Hostlist expressions
+support both ranges and comma-separated numerical lists.
+
+For example:
+
+* ``node[1-2]`` expands to ``node1 node2``
+* ``node[1,3]`` expands to ``node1 node3``
+* ``node[1,5-6]`` expands to ``node1 node5 node6``
diff --git a/userdocs/index.rst b/userdocs/index.rst
index 125a5dc0..a6f342d1 100644
--- a/userdocs/index.rst
+++ b/userdocs/index.rst
@@ -14,6 +14,7 @@ Welcome to the Warewulf User Guide!
    Control Server Setup <contents/setup>
    Warewulf Installation <contents/installation>
    Warewulf Configuration <contents/configuration>
+   Controlling Warewulf (wwctl) <contents/wwctl>
    Warewulf Initialization <contents/initialization>
    Container Management <contents/containers>
    Kernel Management <contents/kernel>