Dvc: Use consistent help messages style everywhere

[shcheklein]

Option/argument:

start lower case (this way we don't have to fix help thing), no dot after

Command description:

Upper case, dots, sentences.

[ghost]

@shcheklein, just to make sure that I understand what's the issue and the suggested solution; you want the options/arguments (like --quiet or init) to start with lowercase and exclude dots or punctuation characters (as they currently do), and the description to start with uppercase, end with dots, as sentences, right?

I checked all --help outputs and the only change I'm seeing right now with the current dvc version is this one:

usage: dvc [-h] [-q] [-v] [-V] COMMAND ...

Data Version Control

optional arguments:
-  -h, --help     show this help message and exit
+  -h, --help     Show this help message and exit.
  -q, --quiet    Be quiet.
  -v, --verbose  Be verbose.
  -V, --version  Show program's version.

Available Commands:
  COMMAND        Use dvc COMMAND --help for command-specific help.
    init         Initialize dvc over a directory (should already be a git dir).
    destroy      Destroy dvc. Will remove all project's information, data files and cache.
    add          Add files/directories to dvc.
    import       Import files from URL.
    checkout     Checkout data files from cache.
    run          Generate a stage file from a given command and execute the command.
    pull         Pull data files from the cloud.
    push         Push data files to the cloud.
    fetch        Fetch data files from the cloud.
    status       Show the project status.
    repro        Reproduce DVC file. Default file name - 'Dvcfile'.
    remove       Remove outputs of DVC file.
    move         Move output of DVC file.
    unprotect    Unprotect data file/directory.
    gc           Collect garbage.
    config       Get or set config options.
    remote       Manage set of tracked repositories.
    metrics      Get metrics from all branches.
    install      Install dvc hooks into the repository.
    root         Relative path to project's directory.
    lock         Lock DVC file.
    unlock       Unlock DVC file.
    pipeline     Manage pipeline.

That's the default --help description, but I can submit a PR to format it like the diff above

[shcheklein]

@mroutis

First of all, we should check help (styling, syntax, descriptions) for other commands and make them follow the same style. This ticket is not about main help message only.

Then, I think my initial intention was wrong. I was thing to make arguments descriptions look like:

pipeline manage pipeline

while description like:

Data Version Control - some description.

This way we don't have to fix --help built-in lowercase description.

Since that time, I realized that there are some commands with arguments that have multiple sentence descriptions:

show Sentence description1. Sentence description1.

If we can review and simplify them, I would vote for all-lowercase (and keep built-in --help description as is). @efiop has more context if it's doable/makes sense. Otherwise let's change --help to a custom that starts with upper case.

Let me know if it makes sense.

[Hiyorimi]

Working on this

[efiop]

@Hiyorimi Let us know if you have any questions :slightly_smiling_face:

[Hiyorimi]

@efiop I have to note only one thing:

output with my PR changes to be like this:

dvc -h                                                                                                                                          10.10.19 2:39
usage: dvc [-q | -v] [-h] [-V] COMMAND ...

Data Version Control

optional arguments:
  -q, --quiet    Be quiet.
  -v, --verbose  Be verbose.
  -h, --help     Show this help message and exit.
  -V, --version  Show program's version.

One may note that 'help' arg can be moved upper in list, but as far as I went deep into argparse source code and Stack Overflow questions on the matter, there is no easy and painless way to improve it.

As I have noted in the comment, adding help argument in get_parent_parser() either in log_level_group or on parent_parser itself will cause unexpected error upon parameter invoke.

[Hiyorimi]

@efiop Since nobody simplified commands to one sentence descriptions, I just turned --help message to uppercase.