Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature] document a materialization #9841

Closed
3 tasks done
salimmoulouel opened this issue Apr 2, 2024 · 1 comment
Closed
3 tasks done

[Feature] document a materialization #9841

salimmoulouel opened this issue Apr 2, 2024 · 1 comment
Labels
dbt-docs [dbt feature] documentation site, powered by metadata artifacts enhancement New feature or request wontfix Not a bug or out of scope for dbt-core

Comments

@salimmoulouel
Copy link

salimmoulouel commented Apr 2, 2024

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

@salimmoulouel salimmoulouel added enhancement New feature or request triage labels Apr 2, 2024
@dbeatty10 dbeatty10 self-assigned this Apr 2, 2024
@dbeatty10
Copy link
Contributor

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:

image

@dbeatty10 dbeatty10 closed this as not planned Won't fix, can't repro, duplicate, stale Apr 2, 2024
@dbeatty10 dbeatty10 added wontfix Not a bug or out of scope for dbt-core and removed triage labels Apr 2, 2024
@dbeatty10 dbeatty10 removed their assignment Apr 2, 2024
@dbeatty10 dbeatty10 added the dbt-docs [dbt feature] documentation site, powered by metadata artifacts label Apr 2, 2024
mirnawong1 added a commit to dbt-labs/docs.getdbt.com that referenced this issue Apr 4, 2024
[Preview](https://docs-getdbt-com-git-dbeatty10-patch-1-dbt-labs.vercel.app/faqs/Docs/documenting-macros#document-a-custom-materialization)

## What are you changing in this pull request and why?

dbt-labs/dbt-core#9841 asked about documenting
custom materializations, and this PR explains how to document the
macro(s) associated with each custom materialization.

## Checklist
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [x] I tested that the code example works
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dbt-docs [dbt feature] documentation site, powered by metadata artifacts enhancement New feature or request wontfix Not a bug or out of scope for dbt-core
Projects
None yet
Development

No branches or pull requests

2 participants