Add per-subcommand help using abra help <subcommand> #61

3wordchant · 2020-12-30T21:06:12Z

3wordchant commented

2020-12-30 21:06:12 +00:00

Closes #50

Didn't wanna get too far into defining help because it's going to require some fun editing once #60 lands, but I hope the concept with help_app_ls etc. is clear.

Try running abra help foobar and you'll get a list of available per-command help.

Closes #50 Didn't wanna get too far into defining help because it's going to require some fun editing once #60 lands, but I hope the concept with `help_app_ls` etc. is clear. Try running `abra help foobar` and you'll get a list of available per-command help.

3wordchant requested review from decentral1se 2020-12-30 21:07:25 +00:00

3wordchant referenced this pull request

2020-12-30 21:21:24 +00:00

Document the CLI within the docopt setup #50

decentral1se commented

2020-12-30 21:22:43 +00:00

#60 bomb dropped!

[#60](https://git.autonomic.zone/coop-cloud/abra/pulls/60) bomb dropped!

decentral1se reviewed 2020-12-30 21:37:03 +00:00

decentral1se left a comment

Never seen help <cmd>_<sub-cmd> style help so feeling a bit put off by that but I don't want to drown you in my subjectivities again ;) Any way to get this sort of help popping out for -h/--help? Looking good though! This will really bring polish to the CLI.

Never seen `help <cmd>_<sub-cmd>` style help so feeling a bit put off by that but I don't want to drown you in my subjectivities again ;) Any way to get this sort of help popping out for `-h/--help`? Looking good though! This will really bring polish to the CLI.

3wordchant commented

2020-12-31 09:00:10 +00:00

Thanks for the review!

Never seen help _ style help so feeling a bit put off by that...

Mm it's not ideal..

Any way to get this sort of help popping out for -h/--help?

.. and yeah that would be best, 💯

I got stuck on docopt recognising commands: four ways I could think of doing that, all of which seemed mega-hairy:

Add a bunch of duplication to the docopt definition, e.g.

  abra [options] app <domain> cp <src> <dst>
  abra [options] app [<domain>] cp [<src>] [<dst>] --help

➕ Doesn't require user to provide a bunch of arguments, works more like git / docker
➖ Doubles the number of docopt lines
➖ Maybe risks docopt entries clobbering each other? Not sure how reliably it'll distinguish abra app cp --help from abra app <domain> --help

Use existing docopt lines, only provide help if you provide all other command args, e.g.

abra app foo_bar_com cp foo bar --help

➕ Doesn't require additional docopt lines – I think I got this working already in command_help_1 with the existing [options] def
➖ No help available until you put all the required args in, i.e. abra app cp --help → generic usage message, abra app foo_bar_com cp --help → generic usage message, abra app foo_bar_com cp src --help → generic usage message, only abra app foo_bar_com cp src dst → help for app cp

Use a docopt sub-parser for each command, and use the --help arg to show a usage message just for that command.

➕ Probably gets us the same behaviour as git and docker, although NB Docker is fussy about where --help is applied:

$ docker run alpine --help
docker: Error response from daemon: OCI runtime create failed: container_linux.go:370: starting container process caused: exec: "--help": executable file not found in $PATH: unknown.

(git is a little fussy but not as bad, git branch -a --help will fail if you're not in a git repo whereas git branch --help works everywhere)

➖ No idea how to actually do this

Switch command order and use a combination character like wp-cli, e.g.

abra [options] app:cp <domain> <src> <dst>
abra help <subcommand>

and then:

abra help app:cp
abra app:cp --help # maybe?

➕ Neat docopt
➕ Command name for help is consistent with the actual command
➖ Back to annoying systemd-style verb-first behaviour, running abra app:deploy foo_bar_com followed by abra app:logs foo_bar_com requires lots of keystrokes or advanced Bash-fu (!!:gs/deploy/logs or ^deploy^logs)

Any preferences between these?

Thanks for the review! > Never seen help <cmd>_<sub-cmd> style help so feeling a bit put off by that... Mm it's not ideal.. > Any way to get this sort of help popping out for -h/--help? .. and yeah that would be best, 💯 I got stuck on `docopt` recognising commands: four ways I could think of doing that, all of which seemed mega-hairy: 1. Add a bunch of duplication to the `docopt` definition, e.g. ``` abra [options] app <domain> cp <src> <dst> abra [options] app [<domain>] cp [<src>] [<dst>] --help ``` * ➕ Doesn't require user to provide a bunch of arguments, works more like `git` / `docker` * ➖ Doubles the number of `docopt` lines * ➖ Maybe risks `docopt` entries clobbering each other? Not sure how reliably it'll distinguish `abra app cp --help` from `abra app <domain> --help` 2. Use existing docopt lines, only provide help if you provide all other command args, e.g. ``` abra app foo_bar_com cp foo bar --help ``` * ➕ Doesn't require additional docopt lines – I think I got this working already in `command_help_1` with the existing `[options]` def * ➖ No help available until you put all the required args in, i.e. `abra app cp --help` → generic usage message, `abra app foo_bar_com cp --help` → generic usage message, `abra app foo_bar_com cp src --help` → generic usage message, only `abra app foo_bar_com cp src dst` → help for `app cp` 3. Use a docopt sub-parser for each command, and use the `--help` arg to show a usage message just for that command. * ➕ Probably gets us the same behaviour as `git` and `docker`, although NB Docker is fussy about where `--help` is applied: ``` $ docker run alpine --help docker: Error response from daemon: OCI runtime create failed: container_linux.go:370: starting container process caused: exec: "--help": executable file not found in $PATH: unknown. ``` (`git` is a little fussy but not as bad, `git branch -a --help` will fail if you're not in a git repo whereas `git branch --help` works everywhere) * ➖ No idea how to actually do this 4. Switch command order and use a combination character like wp-cli, e.g. ``` abra [options] app:cp <domain> <src> <dst> abra help <subcommand> ``` and then: ``` abra help app:cp abra app:cp --help # maybe? ``` * ➕ Neat `docopt` * ➕ Command name for `help` is consistent with the actual command * ➖ Back to annoying systemd-style verb-first behaviour, running `abra app:deploy foo_bar_com` followed by `abra app:logs foo_bar_com` requires lots of keystrokes or advanced Bash-fu (`!!:gs/deploy/logs` or `^deploy^logs`) --- Any preferences between these?

decentral1se commented

2020-12-31 13:03:25 +00:00

Thanks for this epic review of the options.

What I like about our solution is that it is quite constrained by the wonders of Bash and Docopt and this feels like we're going against the grain here.

Should we just figure out how to write a man page so we can man abra and add a one-liner in the docopt definition that you can run man abra for more?

Thanks for this epic review of the options. What I like about our solution is that it is quite constrained by the wonders of Bash and Docopt and this feels like we're going against the grain here. Should we just figure out how to write a man page so we can `man abra` and add a one-liner in the docopt definition that you can run `man abra` for more?

decentral1se commented

2020-12-31 13:09:10 +00:00

Potentials:

Potentials: - https://github.com/tobimensch/cli2man - https://github.com/ghostsquad/ronn2docopt - https://asciidoctor.org/docs/user-manual/#man-pages

3wordchant commented

2020-12-31 18:45:11 +00:00

What I like about our solution is that it is quite constrained by the wonders of Bash and Docopt and this feels like we're going against the grain here.

Yeah I was having the same thought, how much docopt-torturing is too much 😬

Long as my review was, I missed an obvious option tho:

abra [options] help <subcommand>...

then:

abra help app ls

Then we just combine $abra__subcommand_ options with underscores and we can even re-use my existing dubious help_app_ls convention.

Whaddya reck?

> What I like about our solution is that it is quite constrained by the wonders of Bash and Docopt and this feels like we're going against the grain here. Yeah I was having the same thought, how much docopt-torturing is too much 😬 --- Long as my review was, I missed an obvious option tho: `abra [options] help <subcommand>...` then: `abra help app ls` Then we just combine `$abra__subcommand_` options with underscores and we can even re-use my existing dubious `help_app_ls` convention. Whaddya reck?

3wordchant force-pushed command_help_2 from 7ec625e329 to 5411c85793

2020-12-31 23:44:45 +00:00

Compare

3wordchant added 1 commit 2020-12-31 23:46:22 +00:00

continuous-integration/drone/pr Build is passing Details

886ae5b7f2 Fix help function names

decentral1se approved these changes 2021-01-01 11:10:00 +00:00

decentral1se left a comment

🌈

abra [options] help <subcommand>...

🌈 `abra [options] help <subcommand>...`

3wordchant added 1 commit 2021-01-01 12:09:59 +00:00