Update help text for commands + params in CLI and top-level API

.gitattributes

@@ -1,2 +1,5 @@
 core/dbt/include/index.html binary
 tests/functional/artifacts/data/state/*/manifest.json binary
+core/dbt/docs/build/html/searchindex.js binary
+core/dbt/docs/build/html/index.html binary
+performance/runner/Cargo.lock binary

core/dbt/cli/main.py

@@ -129,7 +129,7 @@ def cli(ctx, **kwargs):
 @requires.runtime_config
 @requires.manifest
 def build(ctx, **kwargs):
-    """Run all Seeds, Models, Snapshots, and tests in DAG order"""
+    """Run all seeds, models, snapshots, and tests in DAG order"""
     task = BuildTask(
         ctx.obj["flags"],
         ctx.obj["runtime_config"],
@@ -241,7 +241,6 @@ def docs_serve(ctx, **kwargs):
 @p.full_refresh
 @p.indirect_selection
 @p.introspect
-@p.parse_only
 @p.profile
 @p.profiles_dir
 @p.project_dir
@@ -285,7 +284,8 @@ def compile(ctx, **kwargs):
 @p.version_check
 @requires.preflight
 def debug(ctx, **kwargs):
-    """Show some helpful information about dbt for debugging. Not to be confused with the --debug option which increases verbosity."""
+    """Test the database connection and show information for debugging purposes. Not to be confused with the --debug option which increases verbosity."""
+
     task = DebugTask(
         ctx.obj["flags"],
         None,
@@ -380,7 +380,6 @@ def list(ctx, **kwargs):
 # dbt parse
 @cli.command("parse")
 @click.pass_context
-@p.compile_parse
 @p.profile
 @p.profiles_dir
 @p.project_dir
@@ -389,7 +388,6 @@ def list(ctx, **kwargs):
 @p.threads
 @p.vars
 @p.version_check
-@p.write_manifest
 @requires.preflight
 @requires.profile
 @requires.project

core/dbt/cli/params.py

@@ -41,18 +41,11 @@
     default=True,
 )
 
-compile_parse = click.option(
-    "--compile/--no-compile",
-    envvar=None,
-    help="TODO: No help text currently available",
-    default=True,
-)
-
 config_dir = click.option(
     "--config-dir",
     envvar=None,
-    help="If specified, DBT will show path information for this project",
-    type=click.STRING,
+    help="Show the configured location for the profiles.yml file and exit",
+    is_flag=True,
 )
 
 debug = click.option(
@@ -69,7 +62,7 @@
 defer = click.option(
     "--defer/--no-defer",
     envvar="DBT_DEFER",
-    help="If set, defer to the state variable for resolving unselected nodes.",
+    help="If set, resolve unselected nodes by deferring to the manifest within the --state directory.",
 )
 
 enable_legacy_logger = click.option(
@@ -79,7 +72,11 @@
 )
 
 exclude = click.option(
-    "--exclude", envvar=None, type=tuple, cls=MultiOption, help="Specify the nodes to exclude."
+    "--exclude",
+    envvar=None,
+    type=tuple,
+    cls=MultiOption,
+    help="Specify the nodes to exclude.",
 )
 
 fail_fast = click.option(
@@ -106,7 +103,7 @@
 indirect_selection = click.option(
     "--indirect-selection",
     envvar="DBT_INDIRECT_SELECTION",
-    help="Select all tests that are adjacent to selected resources, even if they those resources have been explicitly selected.",
+    help="Choose which tests to select that are adjacent to selected resources. Eager is most inclusive, cautious is most exclusive, and buildable is in between. Empty includes no tests at all.",
     type=click.Choice(["eager", "cautious", "buildable", "empty"], case_sensitive=False),
     default="eager",
 )
@@ -120,35 +117,49 @@
 log_format = click.option(
     "--log-format",
     envvar="DBT_LOG_FORMAT",
-    help="Specify the log format, overriding the command's default.",
+    help="Specify the format of logging to the console and the log file. Use --log-format-file to configure the format for the log file differently than the console.",
     type=click.Choice(["text", "debug", "json", "default"], case_sensitive=False),
     default="default",
 )
 
 log_format_file = click.option(
     "--log-format-file",
     envvar="DBT_LOG_FORMAT_FILE",
-    help="Specify the file log format, overriding the command's default and the value of --log-format.",
+    help="Specify the format of logging to the log file by overriding the default value and the general --log-format setting.",
     type=click.Choice(["text", "debug", "json", "default"], case_sensitive=False),
     default="debug",
 )
 
 log_level = click.option(
     "--log-level",
     envvar="DBT_LOG_LEVEL",
-    help="Specify the minimum severity of events that are logged.",
+    help="Specify the minimum severity of events that are logged to the console and the log file. Use --log-level-file to configure the severity for the log file differently than the console.",
     type=click.Choice(["debug", "info", "warn", "error", "none"], case_sensitive=False),
     default="info",
 )
 
 log_level_file = click.option(
     "--log-level-file",
     envvar="DBT_LOG_LEVEL_FILE",
-    help="Specify the minimum severity of events that are logged to file, overriding the value of --log-level-file.",
+    help="Specify the minimum severity of events that are logged to the log file by overriding the default value and the general --log-level setting.",
     type=click.Choice(["debug", "info", "warn", "error", "none"], case_sensitive=False),
     default="debug",
 )
 
+use_colors = click.option(
+    "--use-colors/--no-use-colors",
+    envvar="DBT_USE_COLORS",
+    help="Specify whether log output is colorized in the console and the log file. Use --use-colors-file/--no-use-colors-file to colorize the log file differently than the console.",
+    default=True,
+)
+
+use_colors_file = click.option(
+    "--use-colors-file/--no-use-colors-file",
+    envvar="DBT_USE_COLORS_FILE",
+    help="Specify whether log file output is colorized by overriding the default value and the general --use-colors/--no-use-colors setting.",
+    default=True,
+)
+
 log_path = click.option(
     "--log-path",
     envvar="DBT_LOG_PATH",
@@ -163,10 +174,11 @@
     hidden=True,
 )
 
+# This less standard usage of --output where output_path below is more standard
 output = click.option(
     "--output",
     envvar=None,
-    help="TODO: No current help text",
+    help="Specify the output format: either JSON or a newline-delimited list of selectors, paths, or names",
     type=click.Choice(["json", "name", "path", "selector"], case_sensitive=False),
     default="selector",
 )
@@ -187,18 +199,11 @@
     "--output",
     "-o",
     envvar=None,
-    help="Specify the output path for the json report. By default, outputs to 'target/sources.json'",
+    help="Specify the output path for the JSON report. By default, outputs to 'target/sources.json'",
     type=click.Path(file_okay=True, dir_okay=False, writable=True),
     default=PurePath.joinpath(Path.cwd(), "target/sources.json"),
 )
 
-parse_only = click.option(
-    "--parse-only",
-    envvar=None,
-    help="TODO:  No help text currently available",
-    is_flag=True,
-)
-
 partial_parse = click.option(
     "--partial-parse/--no-partial-parse",
     envvar="DBT_PARTIAL_PARSE",
@@ -272,6 +277,7 @@
 
 quiet = click.option(
     "--quiet/--no-quiet",
+    "-q",
     envvar="DBT_QUIET",
     help="Suppress all non-error logging to stdout. Does not affect {{ print() }} macro calls.",
 )
@@ -288,7 +294,7 @@
     "--resource-types",
     "--resource-type",
     envvar=None,
-    help="TODO: No current help text",
+    help="Restricts the types of resources that dbt will include",
     type=ChoiceTuple(
         [
             "metric",
@@ -317,7 +323,11 @@
     "type": tuple,
 }
 
-inline = click.option("--inline", envvar=None, help="Pass SQL inline to dbt compile and preview")
+inline = click.option(
+    "--inline",
+    envvar=None,
+    help="Pass SQL inline to dbt compile and preview",
+)
 
 # `--select` and `--models` are analogous for most commands except `dbt list` for legacy reasons.
 # Most CLI arguments should use the combined `select` option that aliases `--models` to `--select`.
@@ -328,7 +338,9 @@
 select = click.option(*select_decls, *model_decls, **select_attrs)
 
 selector = click.option(
-    "--selector", envvar=None, help="The selector name to use, as defined in selectors.yml"
+    "--selector",
+    envvar=None,
+    help="The selector name to use, as defined in selectors.yml",
 )
 
 send_anonymous_usage_stats = click.option(
@@ -339,7 +351,10 @@
 )
 
 show = click.option(
-    "--show", envvar=None, help="Show a sample of the loaded data in the terminal", is_flag=True
+    "--show",
+    envvar=None,
+    help="Show a sample of the loaded data in the terminal",
+    is_flag=True,
 )
 
 # TODO:  The env var is a correction!
@@ -356,7 +371,11 @@
 )
 
 skip_profile_setup = click.option(
-    "--skip-profile-setup", "-s", envvar=None, help="Skip interactive profile setup.", is_flag=True
+    "--skip-profile-setup",
+    "-s",
+    envvar=None,
+    help="Skip interactive profile setup.",
+    is_flag=True,
 )
 
 # TODO:  The env var and name (reflected in flags) are corrections!
@@ -366,7 +385,7 @@
 state = click.option(
     "--state",
     envvar="DBT_STATE",
-    help="If set, use the given directory as the source for json files to compare with this project.",
+    help="If set, use the given directory as the source for JSON files to compare with this project.",
     type=click.Path(
         dir_okay=True,
         file_okay=False,
@@ -391,7 +410,10 @@
 )
 
 target = click.option(
-    "--target", "-t", envvar=None, help="Which target to load for the given profile"
+    "--target",
+    "-t",
+    envvar=None,
+    help="Which target to load for the given profile",
 )
 
 target_path = click.option(
@@ -409,20 +431,6 @@
     type=click.INT,
 )
 
-use_colors = click.option(
-    "--use-colors/--no-use-colors",
-    envvar="DBT_USE_COLORS",
-    help="Specify whether log output is colorized.",
-    default=True,
-)
-
-use_colors_file = click.option(
-    "--use-colors-file/--no-use-colors-file",
-    envvar="DBT_USE_COLORS_FILE",
-    help="Specify whether log file output is colorized overriding --use-colors/--no-use-colors.",
-    default=True,
-)
-
 use_experimental_parser = click.option(
     "--use-experimental-parser/--no-use-experimental-parser",
     envvar="DBT_USE_EXPERIMENTAL_PARSER",
@@ -449,18 +457,20 @@ def _version_callback(ctx, _param, value):
 
 version = click.option(
     "--version",
+    "-V",
+    "-v",
     callback=_version_callback,
     envvar=None,
     expose_value=False,
-    help="Show version information",
+    help="Show version information and exit",
     is_eager=True,
     is_flag=True,
 )
 
 version_check = click.option(
     "--version-check/--no-version-check",
     envvar="DBT_VERSION_CHECK",
-    help="Ensure dbt's version matches the one specified in the dbt_project.yml file ('require-dbt-version')",
+    help="If set, ensure the installed dbt version matches the require-dbt-version specified in the dbt_project.yml file (if any). Otherwise, allow them to differ.",
     default=True,
 )
 
@@ -484,13 +494,6 @@ def _version_callback(ctx, _param, value):
 write_json = click.option(
     "--write-json/--no-write-json",
     envvar="DBT_WRITE_JSON",
-    help="Writing the manifest and run_results.json files to disk",
-    default=True,
-)
-
-write_manifest = click.option(
-    "--write-manifest/--no-write-manifest",
-    envvar=None,
-    help="TODO: No help text currently available",
+    help="Whether or not to write the manifest.json and run_results.json files to the target directory",
     default=True,
 )

core/dbt/cli/requires.py

@@ -144,8 +144,8 @@ def wrapper(*args, **kwargs):
 
 def manifest(*args0, write=True, write_perf_info=False):
     """A decorator used by click command functions for generating a manifest
-    given a profile, project, and runtime config. This also registers the adaper
-    from the runtime config and conditionally writes the manifest to disc.
+    given a profile, project, and runtime config. This also registers the adapter
+    from the runtime config and conditionally writes the manifest to disk.
     """
 
     def outer_wrapper(func):

tests/functional/partial_parsing/test_pp_docs.py

@@ -223,7 +223,7 @@ def models(self):
         }
 
     def test_remove_replace(self, project):
-        run_dbt(["parse", "--write-manifest"])
+        run_dbt(["parse"])
         manifest = get_manifest(project.project_root)
         doc_id = "doc.test.whatever"
         assert doc_id in manifest.docs
@@ -243,7 +243,7 @@ def test_remove_replace(self, project):
         rm_file(project.project_root, "models", "my_model.md")
         # remove description from schema file
         write_file(my_model_no_description_yml, project.project_root, "models", "my_model.yml")
-        run_dbt(["parse", "--write-manifest"])
+        run_dbt(["parse"])
         manifest = get_manifest(project.project_root)
         assert doc_id not in manifest.docs
         # The bug was that the file still existed in manifest.files