# Here is a way to write dbt docs as SQL comment

**URL:** <https://discourse.getdbt.com/t/here-is-a-way-to-write-dbt-docs-as-sql-comment/1658>\
**Category:** Show and Tell\
**Tags:** dbt-docs\
**Created:** [September 26, 2020, 4:22am UTC](https://discourse.getdbt.com/t/here-is-a-way-to-write-dbt-docs-as-sql-comment/1658 "2020-09-26T04:22:57Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![daigotanaka](https://sea2.discourse-cdn.com/flex020/user_avatar/discourse.getdbt.com/daigotanaka/32/526_2.png) [@daigotanaka](https://discourse.getdbt.com/u/daigotanaka)\
**Post date:** [September 26, 2020, 4:22am UTC](https://discourse.getdbt.com/t/here-is-a-way-to-write-dbt-docs-as-sql-comment/1658/1 "2020-09-26T04:22:57Z")

</div>

dbt docs took out so much pain of keeping concise and fresh documentation. And it is beautiful!  
But am I alone wanting to keep the documentation even closer to the code, maybe within SQL files themselves, just like Python docstring? I would give no excuse for out-of-sync docs to myself this way.

So, I just created `dbtdocstr` command. You need Python 3 to run this command.

💙 I may not be aware of any similar programs and I may be just embarrassing myself, but I found this little tool to be useful and am hoping that it does good for others, too. 🙂

From [REAME.md](https://github.com/anelendata/dbt_docstring/blob/master/README.md):

## Install

```auto
pip install dbt_docstring

```

## How does it work?

dbtdocstr command scans .sql files under dbt’s models directories and look for a block that begins with ` ```dbt` and end with ` ````. Inside the block you can write the content of the models section of schema.yml corresponding to the current table as specified in [dbt document](https://docs.getdbt.com/docs/building-a-dbt-project/documentation/):

Example (\<dbt\_project\_root\_directory\>/models/api\_key\_status.sql)

````auto
/*
# API key status

This table lists the API keys with the status.

```dbt
columns:
  - name: api_key
    description: API key
    tests:
      - unique
  - name: enabled
    description: True if API key is enabled status
  - name: update_datetime
    description: Last update date and time
```
*/
SELECT
   api_key,
   enabled,
   update_datetime
FROM {{ ref('my_api_key_list') }}

````

Then run:

```auto
dbtdocstr <dbt_project_root_directory>

```

These two files will be auto-generated from each .sql file in the dbt project:

`models/docs.md` :

```auto
{% docs api_key_status %}
# API key status

This table lists the API keys with the status.
{% enddocs %}

```

`models/schema.yml` :

```auto
version: 2
models:
  - name: api_key_status
    description: '{{ docs("api_key_status") }}'
    columns:
      - name: api_key
        description: API key
        tests:
          - unique
      - name: enabled
        description: True if API key is enabled status
      - name: update_datetime
        description: Last update date and time
  - name: ...

```

To see the document generation, use dbt command:

```auto
dbt docs generate
dbt docs serve

```

### Notes

- The doc must be a SQL comment block comment that begins with ‘/_’ and ends with '_/’
- The first comment block will be extracted.
- The dbt block is searched within the first comment block.
- Any text after the dbt block will be ignored.
- dbt’s Docs Blocks feature can be used only for table & view description. Not column descriptions.
- `dbtdocstr --backup <dbt_root_directory>` to create backup files of schema.yml and docs.yml if they exsit.
- You should be able to add test

---

<div class="post-metadata">

**Author:** ![dmitrof](https://avatars.discourse-cdn.com/v4/letter/d/f9ae1b/32.png) [@dmitrof](https://discourse.getdbt.com/u/dmitrof)\
**Post date:** [September 27, 2020, 12:53pm UTC](https://discourse.getdbt.com/t/here-is-a-way-to-write-dbt-docs-as-sql-comment/1658/2 "2020-09-27T12:53:01Z")

</div>

I like that! I was thinking about this as well. Thank you for sharing!

Do you have plans for columns handling?