New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improves dbt --help documentation #1060

Merged
merged 1 commit into from Oct 15, 2018

Conversation

Projects
None yet
2 participants
@mikekaminsky
Copy link
Contributor

mikekaminsky commented Oct 14, 2018

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 comment has been minimized.

Copy link
Contributor

drewbanin commented Oct 14, 2018

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

This comment has been minimized.

Copy link
Contributor Author

mikekaminsky commented Oct 14, 2018

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

This comment has been minimized.

Copy link
Contributor

drewbanin commented Oct 15, 2018

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

@mikekaminsky

This comment has been minimized.

Copy link
Contributor Author

mikekaminsky commented Oct 15, 2018

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

@drewbanin
Copy link
Contributor

drewbanin left a comment

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

dbt/main.py Outdated
formatter_class=argparse.RawTextHelpFormatter,
description="An ELT tool for managing your SQL "
"transformations and data models."
"\nFor more documentation on these comands, visit: "

This comment has been minimized.

@drewbanin

drewbanin Oct 15, 2018

Contributor

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

@mikekaminsky

This comment has been minimized.

Copy link
Contributor Author

mikekaminsky commented Oct 15, 2018

@drewbanin good catch! Fixed.

@drewbanin drewbanin merged commit 1cf12ff into fishtown-analytics:dev/guion-bluford Oct 15, 2018

1 check passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
@drewbanin

This comment has been minimized.

Copy link
Contributor

drewbanin commented Oct 15, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment