Merge lp://qastaging/~jtv/maas/bug-1189742 into lp://qastaging/~maas-committers/maas/trunk

Custom-formatted help output for API operations in the CLI. The default formatting was unhelpful and, in particular, didn't explain how to pass parameters.

Help output for handlers (which do not take parameters) remains unchanged, as does the global help output.

As a simple example, compare the old output:

«
$ ./bin/maas test zone read -h
usage: ./bin/maas test zone read [-h] [-d] [-k] name [data [data ...]]

GET request. Return zone.

positional arguments:
  name
  data

optional arguments:
  -h, --help show this help message and exit
  -d, --debug Display more information about API responses.
  -k, --insecure Disable SSL certificate check
»

...to the new output:

«
$ ./bin/maas test zone read -h
usage: ./bin/maas test zone read [--help] [-d] [-k] name [data [data ...]]

GET request. Return zone.

Positional arguments:
 name

Common command-line options:
    --help, -h
 Show this help message and exit.
    -d, --debug
 Display more information about API responses.
    -k, --insecure
 Disable SSL certificate check
»

The pointless "data" argument is gone, and most sentences are properly capitalised, and spacing is generally a bit more generous. Otherwise, these basic examples should be similar.

A more involved example... Old output:

«
$ ./bin/maas test tag update -h
usage: ./bin/maas test tag update [-h] [-d] [-k] name [data [data ...]]

Update a specific Tag.

positional arguments:
  name
  data

optional arguments:
  -h, --help show this help message and exit
  -d, --debug Display more information about API responses.
  -k, --insecure Disable SSL certificate check

:param name: The name of the Tag to be created. This should be a short
    name, and will be used in the URL of the tag.
:param comment: A long form description of what the tag is meant for.
    It is meant as a human readable description of the tag.
:param definition: An XPATH query that will be evaluated against the
    hardware_details stored for all nodes (output of `lshw -xml`).
»

And new output:

«
$ ./bin/maas test tag update -h
usage: ./bin/maas test tag update [--help] [-d] [-k] name [data [data ...]]

Update a specific Tag.

Positional arguments:
 name

This method accepts keyword arguments. Pass each argument as a
key-value pair with an equals sign between the key and the value:
key1=value1 key2=value key3=value3. Keyword arguments must come after
any positional arguments.

:param name: The name of the Tag to be created. This should be a short
    name, and will be used in the URL of the tag.
:param comment: A long form description of what the tag is meant for.
    It is meant as a human readable description of the tag.
:param definition: An XPATH query that will be evaluated against the
    hardware_details stored for all nodes (output of `lshw -xml`).

Common command-line options:
    --help, -h
 Show this help message and exit.
    -d, --debug
 Display more information about API responses.
    -k, --insecure
 Disable SSL certificate check
»

We could still do better on the usage string, but this was work enough for now!

Jeroen