clarify macro properties aren't supported in dbt_project.yml

[mirnawong1]

After convo with jerco and per slack convo, clarify in the docs that macro properties aren't support in dbt_project.yml file.

adding a note in the following pages:

• https://docs.getdbt.com/reference/dbt_project.yml
• https://docs.getdbt.com/reference/resource-configs/docs
• https://docs.getdbt.com/reference/macro-properties

note - not sure how semantic models/metrics are added here

[netlify]

✅ Deploy Preview for docs-getdbt-com ready!

Name	Link
🔨 Latest commit	f4ccb57
🔍 Latest deploy log	https://app.netlify.com/sites/docs-getdbt-com/deploys/650321268c9f880008ebd6e5
😎 Deploy Preview	https://deploy-preview-3989--docs-getdbt-com.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[mirnawong1]

part of me wonders if i need a project.yml example seeing as the sentence says it supports all yaml files. 🤔

[jtcohen6]

Thank you for following up here @mirnawong1!

There's a distinction between attributes we call "configs" and attributes we call "properties," in that "configs" can be set for many resources at once in dbt_project.yml, and "properties" can only be set for one resource at a time. The fact is that macros and analyses only have properties, and that's why they cannot be configured from dbt_project.yml.

https://docs.getdbt.com/reference/configs-and-properties

I am very supportive of the idea of calling this out explicitly in the various resource pages! I will also just say, this distinction is historical & a bit arbitrary. We have been thinking on & off about how we might change it in the future:

• [CT-2296] [Spike] Remove the distinction between configs and non-configs dbt-core#7157

[jtcohen6]

Recommend updating this note to mention that these configurations aren't supported in dbt_project.yml:

• Macro properties: https://docs.getdbt.com/reference/macro-properties
• Analysis properties: https://docs.getdbt.com/reference/analysis-properties
• Semantic model configs (https://docs.getdbt.com/docs/build/semantic-models) — however we are adding support for this in v1.7 ! (Semantic model configs - enable/disable + groups dbt-core#8502)

[mirnawong1]

thanks so much @jtcohen6 , this is so clear to me now so i really appreciate you breaking it down 🙏

this issue #3997 makes it seems that semantic models are configs, not properties -- is that right?

[mirnawong1]

oh wait, sorry! i see the issue is related to groups only!

[mirnawong1]

hey @dbeatty10 , can i request a tech review for this pr? since creating the pr, I've made the following changes per jerco's feedback:

• created a partial to communicate that certain resource properties can't be set in the dbt_project.yml file. this partial is set for macro, analysis, exposure, and source properties per this doc.
• added explicit clarification in the docs config doc about which resources support dbt_project.yml and yaml settings
• added an explicit list of properties that aren't supported in the dbt_project.yml page

[dbeatty10]

What if we remove all the changes related to website/docs/reference/resource-configs/docs.md out of this PR and put them into a separate one instead?

We could provide code examples for dbt_project.yml similar to enabled

Here's some code that should work:

name: "my_project"
version: "1.0.0"
config-version: 2
profile: "sandcastle"


models:
  my_project:
    +docs:
      show: false

seeds:
  my_project:
    +docs:
      show: false

snapshots:
  my_project:
    +docs:
      show: false

So the generic code examples would look like this:

models:
  [<resource-path>](/reference/resource-configs/resource-path):
    +docs:
      show: true | false

seeds:
  [<resource-path>](/reference/resource-configs/resource-path):
    +docs:
      show: true | false

snapshots:
  [<resource-path>](/reference/resource-configs/resource-path):
    +docs:
      show: true | false

[mirnawong1]

hey @dbeatty10 , i moved it out of this pr and added it here: #4529

[mirnawong1]

will address monday

[dbeatty10]

Thanks for making these clarifications @mirnawong1 ! 🧠

These previews look good:

• Configs, properties, what are they?
• dbt_project.yml

This combined with associated work split out in the following PRs is useful to explain the nuances:

• #4438
• #4439
• #4529

[mirnawong1]

woohooo! thank you Doug!

approved by Doug