search

sodadata / soda-sql

Soda SQL and Soda Spark have been deprecated and replaced by Soda Core. docs.soda.io/soda-core/overview.html
https://docs.soda.io/
Apache License 2.0
61 stars 17 forks source link

Use `short_help` instead of docstring for commands documentation to avoid truncated help screen #147

Closed bastienboutonnet closed 3 years ago

bastienboutonnet commented 3 years ago

Doing soda --help outputs a truncated help message for commands which isn't really user friendly. This is because click somewhat surprisingly (read stupidly?) ingests __doc__ into a censored help message that is truncated (see https://github.com/pallets/click/issues/486)

The only solution as far as I could see (but I might be wrong) is to use the short_help (yes the name is confusing...) in the command() method.

click.command(short_help='a possibly very long help message that will not be truncated')

This would require that we move or duplicate docstrings into this argument, or write a more user-oriented version or it that we put in short_help. In any case it's not ideal but the current truncated help isn't really nice to our users.

There may be a more across-the-board solution as done in this PR: https://github.com/ansible-community/molecule/pull/2768/files (I saw it referenced in the above issue) but I didn't dig into our code enough to see if it's applicable. Looks like we can feed our own help formatter class to click.command() we could extend the base click one with some options that do not truncate the help by default https://click.palletsprojects.com/en/8.0.x/api/#click.Command).

I'll be happy to contribute to a solution as long as:

vijaykiran commented 3 years ago

Thanks @bastienboutonnet added a fix.

Before:

➜ soda --help
Usage: soda [OPTIONS] COMMAND [ARGS]...

  Soda CLI version 2.1.0b18

Options:
  --help  Show this message and exit.

Commands:
  analyze  Analyzes tables in the warehouse and creates scan YAML files...
  create   Creates a new warehouse.yml file and prepares credentials in
           your...

  scan     Computes all measurements and runs all tests on one table.

After:

➜ soda --help
Usage: soda [OPTIONS] COMMAND [ARGS]...

  Soda CLI version 2.1.0b18

Options:
  --help  Show this message and exit.

Commands:
  analyze  Analyze tables and scaffold SCAN YAML
  create   Create a template wareshouse.yml file
  scan     Compute metrics and run tests for a given table