doc: add documentation for --pick option

Part of #311.

Change-Id: I8cf97e0b48593f723af1396dd64f7a1a0c51dc7b

Author: thiell

doc/man/man1/clush.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH CLUSH 1 "2016-02-28" "1.7.1" "ClusterShell User Manual"
+.TH CLUSH 1 "2016-06-16" "1.7.2" "ClusterShell User Manual"
 .SH NAME
 clush \- execute shell commands on a cluster
 .
@@ -190,6 +190,9 @@ path to a file containing a list of single hosts, node sets or node groups, sepa
 .TP
 .BI \-\-topology\fB= FILE
 topology configuration file to use for tree mode
+.TP
+.BI \-\-pick\fB= N
+pick N node(s) at random in nodeset
 .UNINDENT
 .TP
 .B Output behaviour:

doc/man/man1/nodeset.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH NODESET 1 "2016-02-28" "1.7.1" "ClusterShell User Manual"
+.TH NODESET 1 "2016-06-16" "1.7.2" "ClusterShell User Manual"
 .SH NAME
 nodeset \- compute advanced nodeset operations
 .
@@ -137,6 +137,9 @@ split result into contiguous subsets (ie. for nodeset, subsets will contain node
 .TP
 .BI \-\-axis\fB= RANGESET
 for nD nodesets, fold along provided axis only. Axis are indexed from 1 to n and can be specified here either using the rangeset syntax, eg. \(aq1\(aq, \(aq1\-2\(aq, \(aq1,3\(aq, or by a single negative number meaning that the indice is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range.
+.TP
+.BI \-\-pick\fB= N
+pick N node(s) at random in nodeset
 .UNINDENT
 .UNINDENT
 .UNINDENT

doc/sphinx/tools/clush.rst

@@ -77,15 +77,25 @@ For example::
 Selecting all nodes
 """""""""""""""""""
 
-Finally, a special option ``-a`` (without argument) can be used to select
-**all** nodes, in the sense of ClusterShell node groups (see
+The special option ``-a`` (without argument) can be used to select **all**
+nodes, in the sense of ClusterShell node groups (see
 :ref:`node groups configuration <groups-config>` for more details on special
 **all** external shell command upcall).  If not properly configured, the
 ``-a`` option may lead to a runtime error like::
 
     clush: External error: Not enough working external calls (all, or map +
     list) defined to get all node
 
+Picking node(s) at random
+"""""""""""""""""""""""""
+
+Use ``--pick`` with a maximum number of nodes you wish to pick randomly from
+the targeted node set. *clush* will then run only on selected node(s). The
+following example will run a script on a single random node picked from the
+``@compute`` group::
+
+    $ clush -w @compute --pick=1 ./nonreg-single-client-fs-io.sh
+
 Host files
 """"""""""
 

doc/sphinx/tools/nodeset.rst

@@ -422,9 +422,10 @@ patterns" (inherited from :class:`.NodeSet` extended pattern feature, see
 Special operations
 ^^^^^^^^^^^^^^^^^^
 
-Three special operations are currently available: node set slicing, splitting
-on a predefined node count and splitting non-contiguous subsets. There are all
-explained below.
+A few special operations are currently available: node set slicing, splitting
+on a predefined node count, splitting non-contiguous subsets, choosing fold
+axis (for multidimensional node sets) and picking N nodes randomly. They are
+all explained below.
 
 Slicing
 """""""
@@ -567,6 +568,18 @@ useful to fold along the last axis whatever number of dimensions used::
     comp-1-[1-36],comp-2-[1-36],login-[1-2]
 
 
+Picking N node(s) at random
+"""""""""""""""""""""""""""
+
+Use ``--pick`` with a maximum number of nodes you wish to pick randomly from
+the resulting node set (or from the resulting range set with ``-R``)::
+
+    $ nodeset --pick=1 -f node11 node12 node13
+    node12
+    $ nodeset --pick=2 -f node11 node12 node13
+    node[11,13]
+
+
 .. _nodeset-groups:
 
 Node groups

doc/txt/clush.txt

@@ -7,9 +7,9 @@ execute shell commands on a cluster
 -----------------------------------
 
 :Author: Stephane Thiell <[email protected]>
-:Date:   2016-02-28
+:Date:   2016-06-16
 :Copyright: CeCILL-C V1
-:Version: 1.7.1
+:Version: 1.7.2
 :Manual section: 1
 :Manual group: ClusterShell User Manual
 
@@ -144,6 +144,7 @@ Selecting target nodes:
   --hostfile=FILE, --machinefile=FILE
                       path to a file containing a list of single hosts, node sets or node groups, separated by spaces and lines (may be specified multiple times, one per file)
   --topology=FILE     topology configuration file to use for tree mode
+  --pick=N            pick N node(s) at random in nodeset
 
 Output behaviour:
   -q, --quiet         be quiet, print essential output only

doc/txt/nodeset.txt

@@ -7,9 +7,9 @@ compute advanced nodeset operations
 -----------------------------------
 
 :Author: Stephane Thiell <[email protected]>
-:Date:   2016-02-28
+:Date:   2016-06-16
 :Copyright: CeCILL-C V1
-:Version: 1.7.1
+:Version: 1.7.2
 :Manual section: 1
 :Manual group: ClusterShell User Manual
 
@@ -75,6 +75,7 @@ OPTIONS
     --split=MAXSPLIT    split result into a number of subsets
     --contiguous        split result into contiguous subsets (ie. for nodeset, subsets will contain nodes with same pattern name and a contiguous range of indexes, like foobar[1-100]; for rangeset, subsets with consists in contiguous index ranges)"""
     --axis=RANGESET     for nD nodesets, fold along provided axis only. Axis are indexed from 1 to n and can be specified here either using the rangeset syntax, eg. '1', '1-2', '1,3', or by a single negative number meaning that the indice is counted from the end. Because some nodesets may have several different dimensions, axis indices are silently truncated to fall in the allowed range.
+    --pick=N            pick N node(s) at random in nodeset
 
 
 For a short explanation of these options, see ``-h, --help``.