[jira] [Commented] (AURORA-994) Simplify client help output

["Joshua Cohen (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/AURORA-994?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14268602#comment-14268602 ] 

Joshua Cohen commented on AURORA-994:
-------------------------------------

Do we lose the documentation for all of the flags to the individual verbs when we just use argparse's output?

I.e. --ssh-user in the original output pasted above?

I agree that the argparse output is *much* cleaner and easier to parse, but I feel like it's missing a fair bit of detail as well.

> Simplify client help output
> ---------------------------
>
>                 Key: AURORA-994
>                 URL: https://issues.apache.org/jira/browse/AURORA-994
>             Project: Aurora
>          Issue Type: Story
>          Components: Client, Usability
>            Reporter: Bill Farner
>            Assignee: Bill Farner
>
> The default help in the client is overwhelming, as it includes an exhaustive list of commands, subcommands, all options, and no prose.
> Here's a snippet:
> {noformat}
> $ aurora
> Aurora Client version none@Thursday Jan 08, 2015 00:18:27
> Usage:
> ==Commands for tasks
>   task run   [--verbose] [--threads=threads] [--ssh-user=ssh_username] [--executor-sandbox] CLUSTER/ROLE/ENV/NAME[/INSTANCES] unix_command_line
>   task ssh   [--verbose] [--ssh-user=ssh_username] [--executor-sandbox] [--tunnels=PORT:NAME] [--command=unix_command_line] task_instance
> {noformat}
> Meanwhile, the help text already wired into argparse is much more consumable, allowing you to drill down into subcommands:
> {noformat}
> $ aurora -h
> usage: aurora [-h] {task,quota,cron,job,config,sla,beta-update} ...
> positional arguments:
>   {task,quota,cron,job,config,sla,beta-update}
>     task                Work with a task running in an Apache Aurora cluster
>     quota               Work with quota settings for an Apache Aurora cluster
>     cron                Work with entries in the aurora cron scheduler
>     job                 Work with an aurora job
>     config              Work with an aurora configuration file
>     sla                 Work with SLA data in Aurora cluster.
>     beta-update         Interact with the aurora update service.
> optional arguments:
>   -h, --help            show this help message and exit
> {noformat}
> {noformat}
> $ aurora task -h
> usage: aurora task [-h] {run,ssh} ...
> positional arguments:
>   {run,ssh}
>     run       Usage: aurora task run cluster/role/env/job cmd Runs a shell
>               command on machines currently hosting instances of a single job.
>               This feature supports the same command line wildcards that are
>               used to populate a job's commands. This means anything in the
>               {{mesos.*}} and {{thermos.*}} namespaces.
>     ssh       usage: aurora task ssh cluster/role/env/job/instance [args...]
>               Initiate an SSH session on the machine that a task instance is
>               running on.
> optional arguments:
>   -h, --help  show this help message and exit
> {noformat}
> I suggest we drop the {{help}} subcommand and exhaustive help, and only use the output from argparse.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)