Manpage: Update information regarding global filters and multiplexer.

Update the manual page of avocado to match the current status of the multiplexer,
regarding command line options for global filters.

Fix information on command line option -c | --content. It's about variables.

Plus:  cosmetic fixes around.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

avocado/plugins/multiplexer.py

@@ -49,7 +49,7 @@ class Multiplexer(plugin.Plugin):
                                  help='Shows the multiplex tree structure')
 
         self.parser.add_argument('-c', '--contents', action='store_true', default=False,
-                                 help='Keep temporary files generated by tests')
+                                 help="Shows the variant's content (variables)")
         super(Multiplexer, self).configure(self.parser)
 
     def run(self, args):

man/avocado.rst

@@ -6,7 +6,7 @@
 SYNOPSIS
 ========
 
- avocado [-h] [-v] [-V] [--logdir LOGDIR] [--loglevel LOG_LEVEL] [--plugins PLUGINS_DIR]
+ avocado [-h] [-v] [--logdir LOGDIR] [--loglevel LOG_LEVEL] [--plugins PLUGINS_DIR]
  {run,list,sysinfo,multiplex,plugins,datadir} ...
 
 DESCRIPTION
@@ -39,19 +39,25 @@ of avocado subcommands::
  plugins     List all plugins loaded
  datadir     List all relevant directories used by avocado
 
-To get usage instructions for a given subcommand run it with `--help`. Example::
+To get usage instructions for a given subcommand, run it with `--help`. Example::
 
  $ avocado multiplex --help
-
- usage: avocado multiplex [-h] [-t] [-c] [multiplex_file]
+ usage: avocado multiplex [-h] [--filter-only [FILTER_ONLY [FILTER_ONLY ...]]]
+                          [--filter-out [FILTER_OUT [FILTER_OUT ...]]] [-t]
+                          [-c]
+                          [multiplex_file]
 
  positional arguments:
-   multiplex_file  Path to a multiplex file
+   multiplex_file        Path to a multiplex file
 
  optional arguments:
-   -h, --help      show this help message and exit
-   -t, --tree      Shows the multiplex tree structure
-   -c, --contents  Keep temporary files generated by tests
+   -h, --help            show this help message and exit
+   --filter-only [FILTER_ONLY [FILTER_ONLY ...]]
+                         Filter only path(s) from multiplexing
+   --filter-out [FILTER_OUT [FILTER_OUT ...]]
+                         Filter out path(s) from multiplexing
+   -t, --tree            Shows the multiplex tree structure
+   -c, --contents        Shows the variant's content (variables)
 
 
 RUNNING A TEST
@@ -191,23 +197,54 @@ A command by the same name, `multiplex`, is available on the `avocado`
 command line tool, and enables you to see all the test scenarios that can
 be run::
 
- $ avocado multiplex tests/sleeptest.py.data/sleeptest.yaml
+ $ avocado multiplex examples/tests/sleeptest.py.data/sleeptest.yaml
  Variants generated:
- Variant 1:    ["short={'sleep_length': 0.5}"]
- Variant 2:    ["medium={'sleep_length': 1}"]
- Variant 3:    ["long={'sleep_length': 5}"]
- Variant 4:    ["longest={'sleep_length': 10}"]
+ Variant 1:    /short
+     sleep_length: 0.5
+ Variant 2:    /medium
+     sleep_length: 1
+ Variant 3:    /long
+     sleep_length: 5
+ Variant 4:    /longest
+     sleep_length: 10
 
- $ avocado run --multiplex tests/sleeptest.py.data/sleeptest.yaml sleeptest
+ $ avocado run --multiplex examples/tests/sleeptest.py.data/sleeptest.yaml sleeptest
 
 And the output should look like::
 
- ...
- (1/4) sleeptest.py: PASS (0.50 s)
- (2/4) sleeptest.py.1: PASS (1.00 s)
- (3/4) sleeptest.py.2: PASS (5.01 s)
- (4/4) sleeptest.py.3: PASS (10.01 s)
- ...
+ JOB ID    : <id>
+ JOB LOG   : /home/<user>/avocado/job-results/job-<date-<shortid>/job.log
+ TESTS     : 4
+ (1/4) sleeptest.py.1:  PASS (0.50 s)
+ (2/4) sleeptest.py.2:  PASS (1.00 s)
+ (3/4) sleeptest.py.3:  PASS (5.01 s)
+ (4/4) sleeptest.py.4:  PASS (10.01 s)
+ PASS      : 4
+ ERROR     : 0
+ FAIL      : 0
+ SKIP      : 0
+ WARN      : 0
+ NOT FOUND : 0
+ TIME      : 16.53 s
+
+The `multiplex` plugin and the test runner supports two kinds of global
+filters, through the command line options `--filter-only` and `--filter-out`.
+The `filter-only` exclusively includes one or more paths and
+the `filter-out` removes one or more paths from being processed.
+
+From the previous example, if we are interested to use the variants `/medium`
+and `longest`, we do the following command line::
+
+ $ avocado run --multiplex examples/tests/sleeptest.py.data/sleeptest.yaml sleeptest \
+       --filter-only /medium /longest
+
+And if you want to remove `/small` from the variants created,
+we do the following::
+
+ $ avocado run --multiplex examples/tests/sleeptest.py.data/sleeptest.yaml sleeptest \
+       --filter-out /medium
+
+Note that both filters can be arranged in the same command line.
 
 DEBUGGING BINARIES RUN AS PART OF A TEST
 ========================================