dbt-labs / dbt-labs/dbt

[Feature] Read .sql files for docs blocks

Open
#12,798 4 comments 0 reactions 0 assignees View on GitHub
engine:v1 status:triage type:feature
Dominant language
Rust
Stars
13.8k
Forks
2.6k
Avg merge
21h 31m
Merged PRs (30d)
56

Description

### Is this your first time submitting a feature request?

- [x] I have read the [expectations for open source contributors](https://docs.getdbt.com/docs/contributing/oss-expectations)
- [x] I have searched the existing issues, and I could not find an existing issue for this feature
- [x] I am requesting a straightforward extension of existing dbt functionality, rather than a Big Idea better suited to a discussion

### Describe the feature

Currently only .md files are read and searched for docs blocks. I would like to be able to write docs blocks at the tops of our models. For example:

**my_model.sql**
```
{% docs my_model %}
The description of my model
{% enddocs %}
select *
from my_table
```

**_marts.yml**
```
models:
- name: my_model
description: "{{ doc('my_model') }}"
```

So I propose that `dbt generate docs` also scans .sql files for docs blocks. Or that maybe a new option can be set in `dbt_project.yml`. E.g. `docs-extentions: [".md", ".sql"]`

### Describe alternatives you've considered

I've considered using the Python module [dbt_docstring](https://pypi.org/project/dbt-docstring/). But that would involve another step in the development process, and/or pre-commit hooks etc. I'd prefer to make use of the functionality of dbt which is already there: docs blocks.

### Who will this benefit?

Developers who want to see (and update) the model's description while editing the model.

### Are you interested in contributing this feature?

No

### Anything else?

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.