From ac47dcdc9edf0aeb743ab145a0b02aefa1ad2c8e Mon Sep 17 00:00:00 2001
From: benpankow <ben@dagsterlabs.com>
Date: Thu, 6 Jun 2024 07:42:03 -0700
Subject: [PATCH] [docs] add dbt code references guide

---
 docs/content/api/modules.json.gz              | Bin 1463602 -> 1463602 bytes
 docs/content/api/searchindex.json.gz          | Bin 70992 -> 70992 bytes
 docs/content/api/sections.json.gz             | Bin 527436 -> 527436 bytes
 .../guides/dagster/code-references.mdx        |  42 +++++++++++++++++-
 .../with_dbt_code_references.py               |  30 +++++++++++++
 5 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 examples/docs_snippets/docs_snippets/guides/dagster/code_references/with_dbt_code_references.py

diff --git a/docs/content/api/modules.json.gz b/docs/content/api/modules.json.gz
index 8406f90943c26e89f7dad88b5adfbb52385e5c93..2f0515109e81cf5cbde9d2ed054aa59f206da1d2 100644
GIT binary patch
delta 83
zcmWN_xe<a;007YeWchN)p^(x5T~GtTZ^14MHnI~!X6O%I_>Mgudu0BH@LhjMBB^BZ
dkX-I5B*;@rsic-hUeZb@y$te}kBleNvR!U<68``I

delta 83
zcmWN_yAecC06@{fy59P;OR51)C_<nd!HskxG^0OGc&>B1&W-5^AzOANl2{V?NGk7S
Z667nn6jDkhwKUR7C%ydSFT>3^uMbiW5}E)2

diff --git a/docs/content/api/searchindex.json.gz b/docs/content/api/searchindex.json.gz
index dd3eedef6fb30cc2f291f46ef7bc5499f9836778..2d28f17840e233cb842731968e1d112c93153ecf 100644
GIT binary patch
delta 20
bcmcbxisiy87B=~A4vuW+Mz*bNj9#JuOw0xi

delta 20
bcmcbxisiy87B=~A4h{~-Mz*bNj9#JuNkIju

diff --git a/docs/content/api/sections.json.gz b/docs/content/api/sections.json.gz
index 98b080f19608a5f366e0859c2f0ceb4231e6dfe1..4b4c870698138b37bb5ab1fde0d8f6c6b88510d8 100644
GIT binary patch
delta 41
vcmX>zL*dK}1vdF^4vsA6Mz&Tq##T0_RyO8VHkMX4)>by42>Vtx4mTbE_uUEm

delta 41
vcmX>zL*dK}1vdF^4i0w5Mz&Tq##T0_RyO8VHkMX4)>by42>Vtx4mTbE><I~$

diff --git a/docs/content/guides/dagster/code-references.mdx b/docs/content/guides/dagster/code-references.mdx
index 5f9e15fcdb6c6..8edc815cc8308 100644
--- a/docs/content/guides/dagster/code-references.mdx
+++ b/docs/content/guides/dagster/code-references.mdx
@@ -29,7 +29,9 @@ To complete the steps in this guide, you'll need:
 
 ## Automatically attaching code references to asset definitions
 
-To automatically attach code references to the asset's function definition, you can use the `dagster._core.definitions.metadata.with_source_code_references` utility. Any asset definitions passed to the utility will have their source file attached as metadata.
+### Assets defined in Python
+
+To automatically attach code references to Python assets' function definitions, you can use the `dagster._core.definitions.metadata.with_source_code_references` utility. Any asset definitions passed to the utility will have their source file attached as metadata.
 
 ```python file=/guides/dagster/code_references/with_source_code_references.py
 from dagster import Definitions, asset
@@ -58,6 +60,43 @@ A link to the asset's source in `with_source_code_references.py` will then be vi
   />
 </center>
 
+### dbt assets
+
+Dagster's dbt integration can automatically attach references to the SQL files backing your dbt assets. To enable this feature, set the `enable_code_references` parameter to `True` in the <PyObject module="dagster_dbt" object="DagsterDbtTranslatorSettings" /> passed to your <PyObject module="dagster_dbt" object="DagsterDbtTranslator" />:
+
+```python file=/guides/dagster/code_references/with_dbt_code_references.py
+from pathlib import Path
+
+from dagster_dbt import (
+    DagsterDbtTranslator,
+    DagsterDbtTranslatorSettings,
+    DbtCliResource,
+    dbt_assets,
+)
+
+from dagster import AssetExecutionContext, Definitions
+from dagster._core.definitions.metadata import with_source_code_references
+
+manifest_path = Path("path/to/dbt_project/target/manifest.json")
+
+# links to dbt model source code from assets
+dagster_dbt_translator = DagsterDbtTranslator(
+    settings=DagsterDbtTranslatorSettings(enable_code_references=True)
+)
+
+
+@dbt_assets(
+    manifest=manifest_path,
+    dagster_dbt_translator=dagster_dbt_translator,
+)
+def my_dbt_assets(context: AssetExecutionContext, dbt: DbtCliResource):
+    yield from dbt.cli(["build"], context=context).stream()
+
+
+# optionally, add references to the Python source with with_source_code_references
+defs = Definitions(assets=with_source_code_references([my_dbt_assets]))
+```
+
 ---
 
 ## Manually attaching code references to asset definitions
@@ -83,6 +122,7 @@ from dagster._core.definitions.metadata import (
             code_references=[
                 LocalFileCodeReference(
                     file_path=os.path.join(os.path.dirname(__file__), "source.yaml"),
+                    # Label and line number are optional
                     line_number=1,
                     label="Model YAML",
                 )
diff --git a/examples/docs_snippets/docs_snippets/guides/dagster/code_references/with_dbt_code_references.py b/examples/docs_snippets/docs_snippets/guides/dagster/code_references/with_dbt_code_references.py
new file mode 100644
index 0000000000000..8f2cf0f2a452b
--- /dev/null
+++ b/examples/docs_snippets/docs_snippets/guides/dagster/code_references/with_dbt_code_references.py
@@ -0,0 +1,30 @@
+from pathlib import Path
+
+from dagster_dbt import (
+    DagsterDbtTranslator,
+    DagsterDbtTranslatorSettings,
+    DbtCliResource,
+    dbt_assets,
+)
+
+from dagster import AssetExecutionContext, Definitions
+from dagster._core.definitions.metadata import with_source_code_references
+
+manifest_path = Path("path/to/dbt_project/target/manifest.json")
+
+# links to dbt model source code from assets
+dagster_dbt_translator = DagsterDbtTranslator(
+    settings=DagsterDbtTranslatorSettings(enable_code_references=True)
+)
+
+
+@dbt_assets(
+    manifest=manifest_path,
+    dagster_dbt_translator=dagster_dbt_translator,
+)
+def my_dbt_assets(context: AssetExecutionContext, dbt: DbtCliResource):
+    yield from dbt.cli(["build"], context=context).stream()
+
+
+# optionally, add references to the Python source with with_source_code_references
+defs = Definitions(assets=with_source_code_references([my_dbt_assets]))