yellow team mailing list archive

[Francesco Banconi <francesco.banconi@xxxxxxxxxxxxx>]

The proposal to merge lp:~frankban/lpsetup/help-fixes into lp:lpsetup has been updated.

Description changed to:

= Summary =

This branch introduces 2 main changes:

1) Remove step names repetition in subcommands help.

This is achieved easily by overriding the `metavar` while creating the steps actions. By default, argparse generates the metavar (the value displayed as example in the help for a specific argument) using choices where present. Now the metavar is just 'STEP_NAME', and the choices are explicitly listed in the action's help.

2) Make subcommands help more descriptive, adding usage examples.

This is less trivial.

I added a custom argparse HelpFormatter that preserves newlines and tabs. The default one just replaces \s+ with a single space and the uses textwrap.fill() to format the resulting text. Now textwrap.fill() is used on each line, and tabs are preserved: they are used to indent command line examples.

I also introduced the concept of "epilog" in the subcommands protocol, as an optional name. If a subcommand defines an epilog, that value is used when creating the subparser. The epilogs are already supported by the Python argparse library, and represent texts to be added at the end of the auto-generated help messages.

The global help (i.e. `lp-setup help`) epilog is generated collecting subcommands' epilogs. `cli.SUBCOMMANDS` is used to sort all the epilogs. As a consequence, I reordered the subcommands list so that the generated help message makes sense.

Added an epilog for each subcommand: this strongly increased this MP diff.


== Examples ==

Here is the output of `./lp-setup help init-lxc` in trunk:
http://pastebin.ubuntu.com/1162421/

Here is the output of the same command in this branch:
http://pastebin.ubuntu.com/1162422/


== Other changes ==

The help now is wrapped at terminal width. Looking at the argparse code I've seen that HelpFormatter can be instantiated passing a width, representing the number of columns used to wrap the help message. We already have a reliable function that calculates the terminal width, so, I thought this could be a nice improvement.

In the help of optional argument attached to the parser by subcommands we often had the default value explicitly added, e.g. help='the help [DEFAULT={0}]'.format(default_value). I've found that argparse automatically formats the help strings passing a context that already contains the default value. So this branch replaces the line above with: help='the help [DEFAULT=%(default)s]'.

For more details, see:
https://code.launchpad.net/~frankban/lpsetup/help-fixes/+merge/120957
-- 
https://code.launchpad.net/~frankban/lpsetup/help-fixes/+merge/120957
Your team Yellow Squad is requested to review the proposed merge of lp:~frankban/lpsetup/help-fixes into lp:lpsetup.