Here is a way to write dbt docs as SQL comment

Show and Tell
1

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.

:blue_heart: 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. :slightly_smiling_face:

From REAME.md:

Install

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:

Example (<dbt_project_root_directory>/models/api_key_status.sql)

/*
# 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:

dbtdocstr <dbt_project_root_directory>

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

models/docs.md :

{% docs api_key_status %}
# API key status

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

models/schema.yml :

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:

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
7 Likes
2

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

Do you have plans for columns handling?

1 Like