stbt.get_config API change from (key, section='global') to (section, key)

This changes the python API to:

    stbt.get_config(section, key)

Since 9283df1, `get_config` no longer falls back to the "global" config
section, so it makes less sense to provide a default `section`. The
change in parameter order is more consistent with python's
`ConfigParser`, and with our command-line tool `stbt config` (and other
similar command-line tools like `git config`).

I wanted to make this API change now, before there are too many users of
`stbt.get_config`. `stbt.get_config` was only added in the previous
stb-tester release (0.12). Hopefully most users were only passing one
parameter, so now that the second parameter doesn't have a default value
you'd find the API change by running `pylint`. If they were using the
keyword parameter (in 0.12 it was called "tool" instead of "section")
then pylint will also catch the change. Otherwise there will be a
run-time failure because it's highly unlikely you'll have a section in
your config file matching the key you're looking for, with a key
matching the section you're looking for.
stbt config: Nicer error messages
stbt config: API change from `[section] key` to `section.key`

This changes the command-line tool's API to:

    stbt config <section>.<key>

Since 9283df1, the search for a configuration key no longer falls back
to the "global" config section, so it makes less sense to provide a
default section. The new API is consistent with `git config`, and it
will allow us (in future) to add a parameter to specify the default
value should the key not be found in the configuration files.

I wanted to make this change now, before there are too many users of
`stbt config` (which was only added in the previous stb-tester release,
0.12). All current users of the tool will fail: Those specifying two
parameters will fail because now only one parameter is allowed; those
specifying a single parameter will fail because that parameter doesn't
include the section and the key name separated by a dot. So at least
there won't be any confusing silent changes in behaviour.
Move default configuration to a location not writable by the user

The existing configuration search path was:

    1. /etc/stbt/stbt.conf
    2. ~/.config/stbt/stbt.conf
    3. $STBT_CONFIG_FILE

This commit adds a new path *before* the existing paths:

    0. /usr/libexec/stbt/stbt.conf
    1. ...
    2. ...
    3. ...

(assuming a typical installation prefix; exact paths may vary).

This is because /etc/stbt/stbt.conf is intended to be editable by the
user or the system administrator; if that user removes some
configuration entries, `stbt` will now continue to work.

Putting a config file in /usr/libexec may be a bit weird, but it is oh
so convenient for it to be in the same directory as stbt.py. According
to the Filesystem Hierarchy Standard (http://www.pathname.com/fhs/) it
should be in /usr/share, I suppose. On Fedora 17, packages like "rpm"
and "udev" store various configuration files (not executables, not
shared libraries) under /usr/lib/<package>/ so there is a precedent
(but that's lib, not libexec).

Note that `make install` installs stbt.conf to both
/usr/libexec/stbt/stbt.conf and /etc/stbt/stbt.conf. The latter serves
to document all available config options; the user can choose to remove
some entries, and `stbt` continues to work because it finds that entry
in /usr/libexec/stbt/stbt.conf.

Note that I didn't list /usr/libexec/stbt/stbt.conf in the README.rst /
man page, because it isn't something that users should be concerned with;
it's an implementation detail. /usr/lib* is for read-only data.
stbt.py: Cleanup: Rename GStreamer `params` variable to `properties`

This is consistent with GStreamer's nomenclature, and it serves to
clarify the distinction between the GStreamer *properties* (an
implementation detail) and the templatematch *parameters* (passed in by
the user).
README: Clarify documentation of templatematch parameters

* Reference python functions as `detect_match` instead of
  `detect_match()`, for consistency with the rest of the README.

* match_method:
  + Describe the purpose and effect of the cvMatchTemplate algorithm,
    not the implementation detail of what it returns (a "heat map").
  + Correct the possible values (from "sqdiff" to "sqdiff-normed", etc).
  + Don't use a table, because it was causing the following warning to be
    printed when opening the man page with `man` (a bug in groff?):
      grotty:<standard input> (<standard input>):6245: character above first line discarded
      grotty:<standard input> (<standard input>):6249: character above first line discarded
      grotty:<standard input> (<standard input>):6253: character above first line discarded
  + Include the docs.opencv.org URLs in plain text; otherwise they get
    lost when converting to man page format.

* match_threshold:
  + Don't mention the "confirm" stage because it hasn't been introduced yet.
  + Fix spelling of "cvMatchTemplate".
  + Remove irrelevant link to floating-point details.

* confirm_method:
  + Explain why the "confirm" step is needed.
  + Explain that it is run just on the Region of Interest identified by the
    previous step.
  + Move discussion of `normed-absdiff` disadvantages from the `absdiff`
    section (where the normalisation of `normed-absdiff` hasn't been
    explained yet) to the `normed-absdiff` section.
  + Don't recommend specific numbers for the `normed-absdiff`
    `confirm_threshold`, because the useful threshold depends entirely on
    the luminance range of the template and source images.

* erode_passes:
  + Move after `confirm_threshold`, to keep `confirm_method` and
    `confirm_threshold` closer together; this matches the order that the
    `confirm_threshold` and `erode_passes` parameters are used in.
  + Explain that `erode_passes` applies to the "confirm" algorithm.
stbt.py: Cleanup: Move `get_config` function to the top of the file

This is needed by the next commit where I add a function that calls
`get_config` to set the function's default parameter values.

A function's default parameter values are evaluated when the function
is *defined*, not when the function is *called*; so `get_config` needs
to have been defined before that function.
`wait_for_match` etc. take `MatchParameters` argument instead of `**kwargs`

Commit dd44303b changed the `wait_for_match` signature from:

    wait_for_match(
        image,
        timeout_secs=10,
        consecutive_matches=1,
        match_method=1,
        match_threshold=0.8,
        confirm_method=2,
        erode_passes=1,
        confirm_threshold=None,
        noise_threshold=None)

to:

    wait_for_match(
        image,
        timeout_secs=10,
        consecutive_matches=1,
        noise_threshold=None,
        **kwargs)

because the default values for the templatematch-related parameters are
now loaded from stbt.conf.

That made the API slightly more obscure (yes it's documented in the man
page, but developers often like to refer to the source code directly),
and it also meant that tools like pylint won't catch mis-spellings of
those parameter names.

This commit makes the parameters explicit again, but instead of passing
them as individual keyword arguments to `wait_for_match`, you pass in
a `MatchParameters` object.

This saves duplicating all the image processing parameters as keyword
arguments in `wait_for_match`, `detect_match`, `press_until_match`, and
all user-defined functions that wrap the above (of which we have quite a
few at YouView, such as `wait_for_any_match`, `match`, and `match_any`).

The downside is that it makes the call sites quite a bit more verbose.
See for example this change made to one of the selftests in this commit:

    - wait_for_match("$scratchdir/gamut.png", confirm_threshold=0.7)
    + wait_for_match("$scratchdir/gamut.png",
    +                match_parameters=MatchParameters(confirm_threshold=0.7))

The argument in favour of this change is:

+ Advanced users of stb-tester will have quite a lot of their own
  user-defined functions that would benefit from this.

+ The uglyness at the call sites is something that shouldn't be very
  frequent; the image processing algorithm should *just work* most of
  the time without customisation (except for, possibly, global settings
  in stbt.conf).
Move documentation for `MatchParameters` into the source code

Note that this documentation still appears in README.rst, but now in the
section that is automatically populated from the source code docstrings.

A note regarding the changes to api-doc.sh:

We now want to print a class's full docstring, not just the first
paragraph (as delimited by a blank line). Before `MatchParameters`, none
of the classes' docstrings had more than one paragraph. So now we use
everything in the pydoc output up to "Methods defined here" (which pydoc
prints for classes with methods) or to "Method resolution order" (which
pydoc prints for all classes, and is the first thing to appear after the
docstring for classes with no methods explicitly defined in the source
code).
Merge branch 'match-parameters'

The functional change here is commit 25d7f3a9 (`wait_for_match` etc.
take `MatchParameters` argument instead of `**kwargs`). See that commit
message for details.

* match-parameters:
  Move documentation for `MatchParameters` into the source code
  `wait_for_match` etc. take `MatchParameters` argument instead of `**kwargs`
  stbt.py: Cleanup: Move `get_config` function to the top of the file
  README: Clarify documentation of templatematch parameters
  stbt.py: Cleanup: Rename GStreamer `params` variable to `properties`

Closes #25.
stbt remote: New command line tool to send RCU commands with PC keyboard

This is useful when multiple set-top-boxes are under test in the same
room and it is not safe to use the remote controller shipped with the
box to control it manually because the IR signals are received by multiple
boxes.

The tool uses the same remote control implementations as 'stbt run' and
'stbt record'.

A keymap file is required to save mappings of keyboard keys to remote
control keys. The keymap file can be recorded using the tool's
'recording mode' but it was designed to make it easy to create one from
scratch manually. See `stbt remote --help` for detailed information.

As 'curses' library waits for 2 seconds for further keycodes after it
receives an 'Escape' character, using 'Escape' is quite inconvenient and
therefore is not allowed in this implementation.