Example click API usage (#6307)

* Example python lib w click, written docs

Co-authored-by: Chenyu Li <chenyu.li@dbtlabs.com>

core/dbt/cli/__init__.py

@@ -0,0 +1 @@
+from .main import cli as dbt_cli  # noqa

core/dbt/cli/context.py

@@ -0,0 +1,16 @@
+import click
+from typing import Optional
+
+from dbt.cli.main import cli as dbt
+
+
+def make_context(args, command=dbt) -> Optional[click.Context]:
+    try:
+        ctx = command.make_context(command.name, args)
+    except click.exceptions.Exit:
+        return None
+
+    ctx.invoked_subcommand = ctx.protected_args[0] if ctx.protected_args else None
+    ctx.obj = {}
+
+    return ctx

core/dbt/cli/example.py

@@ -0,0 +1,20 @@
+from dbt.cli.main import dbtRunner
+from dbt.config.runtime import load_profile, load_project
+
+if __name__ == "__main__":
+    project_dir = "/Users/chenyuli/git/jaffle_shop"
+    cli_args = ["run", "--project-dir", project_dir]
+
+    # initialize the dbt runner
+    dbt = dbtRunner()
+    # run the command
+    res, success = dbt.invoke(cli_args)
+
+    # preload profile and project
+    profile = load_profile(project_dir, {}, "testing-postgres")
+    project = load_project(project_dir, False, profile, {})
+
+    # initialize the runner with pre-loaded profile and project, you can also pass in a preloaded manifest
+    dbt = dbtRunner(profile=profile, project=project)
+    # run the command, this will use the pre-loaded profile and project instead of loading
+    res, success = dbt.invoke(cli_args)

core/dbt/docs/source/index.rst

@@ -1,4 +1,36 @@
 dbt-core's API documentation
 ============================
+How to invoke dbt commands in python runtime
+--------------------------------------------
+
+Right now the best way to invoke a command from python runtime is to use the `dbtRunner` we exposed
+
+.. code-block:: python
+    from dbt.cli.main import dbtRunner
+    cli_args = ['run', '--project-dir', 'jaffle_shop']
+
+    # initialize the dbt runner
+    dbt = dbtRunner()
+    # run the command
+    res, success = dbt.invoke(args)
+
+You can also pass in pre constructed object into dbtRunner, and we will use those objects instead of loading up from the disk.
+
+.. code-block:: python
+
+    # preload profile and project
+    profile = load_profile(project_dir, {}, 'testing-postgres')
+    project = load_project(project_dir, False, profile, {})
+
+    # initialize the runner with pre-loaded profile and project
+    dbt = dbtRunner(profile=profile, project=project)
+    # run the command, this will use the pre-loaded profile and project instead of loading
+    res, success = dbt.invoke(cli_args)
+
+
+For the full example code, you can refer to `core/dbt/cli/example.py`
+
+API documentation
+-----------------
 
 .. dbt_click:: dbt.cli.main:cli