Add some rudimentary docs for runner input files handling

This gets the basics in a very simplistic fashion.

What's missing is any indication of the availability of this feature
in the argparse created help (the output one sees from
gabbi-run --help). It's not clear what the best way to add this is,
since the feature is being managed outside argparse.

Author: cdent

docs/source/runner.rst

@@ -5,8 +5,9 @@ If there is a running web service that needs to be tested and
 creating a test loader with :meth:`~gabbi.driver.build_tests` is
 either inconvenient or overkill it is possible to run YAML test
 files directly from the command line with the console-script
-``gabbi-run``. It accepts YAML on ``stdin``, generates and runs
-tests and outputs a summary of the results.
+``gabbi-run``. It accepts YAML on ``stdin`` or as multiple file
+arguments, and generates and runs tests and outputs a summary of
+the results.
 
 The provided YAML may not use custom :doc:`fixtures` but otherwise
 uses the default :doc:`format`. :doc:`host` information is either
@@ -19,6 +20,15 @@ or::
 
     gabbi-run http://host:port < /my/test.yaml
 
+To test with one or more files the following command syntax may be
+used::
+
+    gabbi-run http://host:port -- /my/test.yaml /my/other.yaml
+
+.. note:: The filename arguments must come after a ``--`` and all
+          other arguments (host, port, prefix, failfast) must come
+          before the ``--``.
+
 To facilitate using the same tests against the same application mounted
 in different locations in a WSGI server, a ``prefix`` may be provided
 as a second argument::

gabbi/runner.py

@@ -53,10 +53,15 @@ def run():
 
         gabbi-run http://example.com:9999/mountpoint < mytest.yaml
 
-    Use `-x` or `--failfast` to abort after the first error or failure:
+    Use `-x` or `--failfast` to abort after the first error or failure::
 
         gabbi-run -x example.com:9999 /mountpoint < mytest.yaml
 
+    Multiple files may be named as arguments, separated from other arguments
+    by a ``--``. Each file will be run as a separate test suite::
+
+        gabbi-run http://example.com -- /path/to/x.yaml /path/to/y.yaml
+
     Output is formatted as unittest summary information.
     """
     parser = _make_argparser()