Improves dbt --help documentation

[mikekaminsky]

Addresses #1058

New and improved CLI help docs:

$ dbt --help

usage: dbt: data build tool [-h] [--version] [-d] [-S]
                            {init,clean,debug,deps,archive,run,compile,docs,seed,test}
                            ...

An ELT tool for managing your SQL transformations and data models.
For more documentation on these comands, visit: docs.getdbt.com

optional arguments:
  -h, --help            show this help message and exit
  --version             Show version information
  -d, --debug           Display debug logging during dbt execution. Useful for
                                debugging and making bug reports.
  -S, --strict          Run schema validations at runtime. This will surface
                                bugs in dbt, but may incur a performance penalty.

Available sub-commands:
  {init,clean,debug,deps,archive,run,compile,docs,seed,test}
    init                Initialize a new DBT project.
    clean               Delete all folders in the clean-targets list
                        (usually the dbt_modules and target directories.)
    debug               Show some helpful information about dbt for debugging.
                        Not to be confused with the --debug option which increases verbosity.
    deps                Pull the most recent version of the dependencies listed in packages.yml
    archive             Record changes to a mutable table over time.
                        Must be configured in your dbt_project.yml.
    run                 Compile SQL and execute against the current target database.
    compile             Generates executable SQL from source model, test, andanalysis files.
                        Compiled SQL files are written to the target/directory.
    docs                Generate or serve the documentation website for your project.
    seed                Load data from csv files into your data warehouse.
    test                Runs tests on data in deployed models.Run this after `dbt run`

Specify one of these sub-commands and you can find more help from there.

Note: I'm not attached to any of this copy / verbiage. Please pile on if you have improvements.

[drewbanin]

This is great @mikekaminsky! Looks like there are some conflicts to resolve, but this will be a really great addition.

What do you think about linking to docs.getdbt.com? We could link to specific sections for subcommands (eg. dbt run), or just plaster a big link in the main help header.

For documentation on these comands, visit: docs.getdbt.com

There's a great article on CLI design that @jthandy just turned me on to here: https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46

I was thinking of implementing the dbt help subcommand in accordance with the first item in that article. There's a lot of other good stuff in there, but we can try to tackle those points separately.

Thanks for submitting this - it's really great!

[mikekaminsky]

Thanks @drewbanin! I just fixed the conflicts and added the link to the docs in the description. I think adding links for very command would be over-kill (plus, not actually that useful in a CLI).

I think the help ideas described in that post are great. I'd also love tab-completion (in addition to the sub-commands and flags, it'd be even better if dbt could tab-complete model names).

[drewbanin]

Thanks @mikekaminsky! I don't see the docs link in the diff here -- any chance it got lost in a merge?

[mikekaminsky]

@drewbanin bizarre! Must have lost it in the git somewhere. Updated now.

[drewbanin]

one minor nitpick, then LGTM! This is going to be a really great addition to dbt -- thanks for contributing!

[drewbanin]

i so hate to do this to you, but I think this should say "commands" :)

[mikekaminsky]

@drewbanin good catch! Fixed.

[drewbanin]

Thanks @mikekaminsky! This will be going out in our next release, 0.12.0!