Add documentation

Signed-off-by: Theofilos Manitaras <manitaras@cscs.ch>

Author: Theofilos Manitaras

docs/manpage.rst

@@ -905,6 +905,7 @@ If no node can be selected, the test will be marked as a failure with an appropr
       The test is not marked as a failure if not enough nodes are available, but it is skipped instead.
       To enforce a failure, use :option:`--flex-alloc-strict`
 
+
 .. option:: --flex-alloc-strict
 
    Fail flexible tests if their minimum task requirement is not satisfied.
@@ -1059,6 +1060,8 @@ The way the tests are generated and how they interact with the test filtering op
       ``--distribute=NODESTATE`` now matches nodes that are exclusively in state ``NODESTATE``, so that the default ``--distribute=idle`` will match only the Slurm nodes that are in the ``IDLE`` state exclusively.
       To achieve the previous behaviour, you should use ``--distribute=idle*``.
 
+   .. versionchanged:: 4.9
+      ``--distribute=NODESTATE`` now allows you to specify alternative valid states using the ``|`` character.
 
 .. option:: -P, --parameterize=[TEST.]VAR=VAL0,VAL1,...
 

reframe/core/schedulers/__init__.py

@@ -161,9 +161,18 @@ def filter_nodes_by_state(nodelist, state):
         If ``all``, the initial list is returned untouched.
         If ``avail``, only the available nodes will be returned.
         All other values are interpreted as a state string.
+        The pipe character ``|`` can be used as to specify multiple
+        alternative node states and has the highest priority.
         State match is exclusive unless the ``*`` is added at the end of the
         state string.
+        When defining multiple states using ``|``, ``*`` has to be added at
+        the end of each alternative state for which a non-exclusive match is
+        required.
+
     :returns: the filtered node list
+
+    .. versionchanged:: 4.9
+       Support the ``|`` character to filter according to alternative states.
     '''
     if '|' in state:
         allowed_states = state.split('|')