Merge lp:~frankban/lpsetup/help-fixes into lp:lpsetup
Status: | Merged |
---|---|
Approved by: | Francesco Banconi |
Approved revision: | 95 |
Merged at revision: | 75 |
Proposed branch: | lp:~frankban/lpsetup/help-fixes |
Merge into: | lp:lpsetup |
Diff against target: |
547 lines (+305/-34) 10 files modified
lpsetup/argparser.py (+45/-4) lpsetup/cli.py (+32/-10) lpsetup/subcommands/finish_init_target.py (+18/-0) lpsetup/subcommands/init_target.py (+29/-3) lpsetup/subcommands/initlxc.py (+42/-6) lpsetup/subcommands/initrepo.py (+48/-9) lpsetup/subcommands/install_lxc.py (+22/-0) lpsetup/subcommands/update.py (+20/-2) lpsetup/tests/test_argparser.py (+29/-0) lpsetup/tests/test_cli.py (+20/-0) |
To merge this branch: | bzr merge lp:~frankban/lpsetup/help-fixes |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Francesco Banconi (community) | Approve | ||
Brad Crittenden (community) | code | Approve | |
Review via email: mp+120957@code.launchpad.net |
Commit message
Improved help messages.
Description of the change
= 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://
Here is the output of the same command in this branch:
http://
== 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=
Thanks for the fix. The help is much clearer now.
* typo: exaustive -> exhaustive
* I find this text confusing: See -s, --steps help for a list of available steps.
It makes it look like it is suggesting you run 'lp-setup update --steps help' as a new command. How about simply 'See the help above for --steps for the list of available steps.' ?
* Using 'lp-setup -h' I see:
usage: lp-setup [-h]
help}
...
Create and update Launchpad development and testing environments.
optional arguments:
-h, --help show this help message and exit
subcommands: lxc,init- target, init-repo, update, finish- init-target, install- lxc,version, help}
{init-
Is it possible to suppress the multiple display of subcommands in a similar way as you did for steps?
* In HelpFormatter docstring, add a comma to become 'text, preserving'.
* Similarly, "Return text wrapped preserving new lines and tabs." ->
"Return text wrapped while preserving new lines and tabs."
* In cli.py, SUBCOMMANDS could be a tuple. The proper ordering is great to have.
* I find this hard to read: "Also add the help subcommand and the global epilog generated collecting all subcommands' epilogs."
How about:
"Also add the help subcommand and the global epilog, which is generated by collecting the epilogs from all of the subcommands."
Thanks for the changes. The help is so much more readable now.