[Backport 1.6.latest] support doc blocks on versioned models

.changes/unreleased/Fixes-20231004-144148.yaml

@@ -0,0 +1,6 @@
+kind: Fixes
+body: Support docs blocks on versioned model column descriptions
+time: 2023-10-04T14:41:48.843486-05:00
+custom:
+ Author: emmyoop
+ Issue: "8540"

core/dbt/parser/manifest.py

@@ -1115,10 +1115,12 @@ def update_semantic_model(self, semantic_model) -> None:
  database=refd_node.database,
  )
 
- # nodes: node and column descriptions
+ # nodes: node and column descriptions, version columns descriptions
  # sources: source and table descriptions, column descriptions
  # macros: macro argument descriptions
  # exposures: exposure descriptions
+ # metrics: metric descriptions
+ # semantic_models: semantic model descriptions
  def process_docs(self, config: RuntimeConfig):
  for node in self.manifest.nodes.values():
  if node.created_at < self.started_at:

core/dbt/parser/schema_renderer.py

@@ -34,12 +34,18 @@ def _is_norender_key(self, keypath: Keypath) -> bool:
  Return True if it's tests or description - those aren't rendered now
  because they're rendered later in parse_generic_tests or process_docs.
  """
+ # top level descriptions and tests
  if len(keypath) >= 1 and keypath[0] in ("tests", "description"):
  return True
 
+ # columns descriptions and tests
  if len(keypath) == 2 and keypath[1] in ("tests", "description"):
  return True
 
+ # versions
+ if len(keypath) == 5 and keypath[4] == "description":
+ return True
+
  if (
  len(keypath) >= 3
  and keypath[0] in ("columns", "dimensions", "measures", "entities")

dev-requirements.txt

@@ -30,7 +30,7 @@ types-mock
 types-protobuf
 types-python-dateutil
 types-pytz
-types-requests
+types-requests < 2.31.0 # types-requests 2.31.0.8 requires urllib3>=2, but we pin urllib3 ~= 1.0 because of openssl requirement for requests
 types-setuptools
 wheel
 mocker

tests/functional/docs/test_model_version_docs_blocks.py

@@ -0,0 +1,74 @@
+import pytest
+
+from dbt.tests.util import run_dbt
+
+model_1 = """
+select 1 as id, 'joe' as first_name
+"""
+
+model_versioned = """
+select 1 as id, 'joe' as first_name
+"""
+
+docs_md = """
+{% docs model_description %}
+unversioned model
+{% enddocs %}
+
+{% docs column_id_doc %}
+column id for some thing
+{% enddocs %}
+
+{% docs versioned_model_description %}
+versioned model
+{% enddocs %}
+
+"""
+
+schema_yml = """
+models:
+ - name: model_1
+ description: '{{ doc("model_description") }}'
+ columns:
+ - name: id
+ description: '{{ doc("column_id_doc") }}'
+
+ - name: model_versioned
+ description: '{{ doc("versioned_model_description") }}'
+ latest_version: 1
+ versions:
+ - v: 1
+ config:
+ alias: my_alias
+ columns:
+ - name: id
+ description: '{{ doc("column_id_doc") }}'
+ - name: first_name
+ description: 'plain text'
+ - v: 2
+ columns:
+ - name: other_id
+"""
+
+
+class TestVersionedModelDocsBlock:
+ @pytest.fixture(scope="class")
+ def models(self):
+ return {
+ "model_1.sql": model_1,
+ "model_versioned.sql": model_versioned,
+ "schema.yml": schema_yml,
+ "docs.md": docs_md,
+ }
+
+ def test_versioned_doc_ref(self, project):
+ manifest = run_dbt(["parse"])
+ model_1 = manifest.nodes["model.test.model_1"]
+ model_v1 = manifest.nodes["model.test.model_versioned.v1"]
+
+ assert model_1.description == "unversioned model"
+ assert model_v1.description == "versioned model"
+
+ assert model_1.columns["id"].description == "column id for some thing"
+ assert model_v1.columns["id"].description == "column id for some thing"
+ assert model_v1.columns["first_name"].description == "plain text"