[Feature] document a materialization

[salimmoulouel]

Is this your first time submitting a feature request?

• I have read the expectations for open source contributors
• I have searched the existing issues, and I could not find an existing issue for this feature
• I am requesting a straightforward extension of existing dbt functionality, rather than a Big Idea better suited to a discussion

Describe the feature

i want to be able to document a materialization in a yaml file
ex :

version: 1
materializations:
  - name: view_create_drop
    description: the doc of my materialization

when i execute
dbt docs generate and dbt docs serve i want to see my materialization documented

Describe alternatives you've considered

No response

Who will this benefit?

No response

Are you interested in contributing this feature?

No response

Anything else?

No response

[dbeatty10]

Thanks for opening this @salimmoulouel !

Good news: there's already a way you can do this by documenting a macro. It also works in conjunction with docs blocks so you don't have to repeat yourself.

The key insight is that for each of your custom materializations, dbt creates a macro in the following format:

materialization_{materialization_name}_{adapter}

See below for an example you can try out.

Since we already have the capability to document materializations, I'm going to close this as not planned. But any feedback on this capability is welcome.

Example

macros/my_materialization.sql

{% materialization my_materialization_name, default %}
 -- the logic for your custom materialization is in here
{% endmaterialization %}

{% materialization my_materialization_name, adapter='xyz' %}
 -- if you need custom logic for the xyz adapter, then it is in here
{% endmaterialization %}

macros/_macros.yml

version: 2

# Format of macros for materializations:
#   materialization_{materialization_name}_{adapter}

macros:
  - name: materialization_my_materialization_name_default
    description: '{{ doc("my_materialization") }}'

  - name: materialization_my_materialization_name_xyz
    description: '{{ doc("my_materialization") }}'

Generate your docs and launch the website:

dbt docs generate
dbt docs serve

Navigate the to the macros folder and click on one of the macros for your materialization: