[](https://travis-ci.com/daigotanaka/dbt_docstring)
# dbt_docstring
Docstring dbt test & documentation in SQL file
## What is it?
dbt has a test and documentation feature where models/schema.yml is the
definition file. While this is already a big help for testing and
documentation in ELT, not being able to keep documentation in the source code
may cause more documentats out of sync with the source.
dbtdocstr lets you write docment in a docstring style directly in .sql files.
## 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](https://docs.getdbt.com/docs/building-a-dbt-project/documentation/):
Example (<dbt_root>/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`:
```
# This file was auto-generated by dbtdocstr.
# Don't manually update.
# https://github.com/anelendata/dbt_docstring
{% docs api_key_status %}
# API key status
This table lists the API keys with the status.
{% enddocs %}
```
`models/schema.yml`:
```
# This file was auto-generated by dbtdocstr.
# Don't manually update.
# https://github.com/anelendata/dbt_docstring
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.
## Original repository
- https://github.com/anelendata/dbt_docstring
# About this project
This project is developed by
ANELEN and friends. Please check out the ANELEN's
[open innovation philosophy and other projects](https://anelen.co/open-source.html)
---
Copyright © 2020~ Anelen Co., LLC
Raw data
{
"_id": null,
"home_page": "https://github.com/anelendata/dbt_docstring",
"name": "dbt-docstring",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Daigo Tanaka, Anelen Co., LLC",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/85/62/bbe74393ab32277d5955b41587d55282ff0acdd33ab7055d6119374c6f66/dbt_docstring-0.1.4.tar.gz",
"platform": null,
"description": "[](https://travis-ci.com/daigotanaka/dbt_docstring)\n\n# dbt_docstring\n\nDocstring dbt test & documentation in SQL file\n\n## What is it?\n\ndbt has a test and documentation feature where models/schema.yml is the\ndefinition file. While this is already a big help for testing and\ndocumentation in ELT, not being able to keep documentation in the source code\nmay cause more documentats out of sync with the source.\n\ndbtdocstr lets you write docment in a docstring style directly in .sql files.\n\n## Install\n\n```\npip install dbt_docstring\n```\n\n## How does it work?\n\ndbtdocstr command scans .sql files under dbt's models directories and look for\na block that begins with ```` ```dbt```` and end with ```` ``` ````.\nInside the block you can write the content of the models section of schema.yml\ncorresponding to the current table as specified in\n[dbt document](https://docs.getdbt.com/docs/building-a-dbt-project/documentation/):\n\nExample (<dbt_root>/models/api_key_status.sql)\n````\n/*\n# API key status\n\nThis table lists the API keys with the status.\n\n```dbt\ncolumns:\n - name: api_key\n description: API key\n tests:\n - unique\n - name: enabled\n description: True if API key is enabled status\n - name: update_datetime\n description: Last update date and time\n```\n*/\nSELECT\n api_key,\n enabled,\n update_datetime\nFROM {{ ref('my_api_key_list') }}\n````\n\nThen run:\n\n```\ndbtdocstr <dbt_project_root_directory>\n```\n\nThese two files will be auto-generated from each .sql file in the dbt project:\n\n`models/docs.md`:\n```\n# This file was auto-generated by dbtdocstr.\n# Don't manually update.\n# https://github.com/anelendata/dbt_docstring\n\n{% docs api_key_status %}\n# API key status\n\nThis table lists the API keys with the status.\n{% enddocs %}\n```\n\n`models/schema.yml`:\n```\n# This file was auto-generated by dbtdocstr.\n# Don't manually update.\n# https://github.com/anelendata/dbt_docstring\n\nversion: 2\nmodels:\n - name: api_key_status\n description: '{{ docs(\"api_key_status\") }}'\n columns:\n - name: api_key\n description: API key\n tests:\n - unique\n - name: enabled\n description: True if API key is enabled status\n - name: update_datetime\n description: Last update date and time\n - name: ...\n ```\n\nTo see the document generation, use dbt command:\n\n```\ndbt docs generate\ndbt docs serve\n```\n\n### Notes\n\n- The doc must be a SQL comment block comment that begins with '/\\*' and ends with '\\*/'\n- The first comment block will be extracted.\n- The dbt block is searched within the first comment block.\n- Any text after the dbt block will be ignored.\n- dbt's Docs Blocks feature can be used only for table & view description. Not column descriptions.\n- `dbtdocstr --backup <dbt_root_directory>` to create backup files of schema.yml and docs.yml if they exsit.\n\n## Original repository\n\n- https://github.com/anelendata/dbt_docstring\n\n# About this project\n\nThis project is developed by\nANELEN and friends. Please check out the ANELEN's\n[open innovation philosophy and other projects](https://anelen.co/open-source.html)\n\n\n---\n\nCopyright © 2020~ Anelen Co., LLC\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Docstring dbt test & documentation in SQL file",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/anelendata/dbt_docstring"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a5ee9496a569da5938717807ce07d456b9e84a6512ce1dc0dface5fcf6bed2b5",
"md5": "cf738f12271a898155acf34c160b6761",
"sha256": "7455db00b55172e960000bf6402bdd3f51a0cc6ae28b49ea2fdf0c5f02a8bdd2"
},
"downloads": -1,
"filename": "dbt_docstring-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf738f12271a898155acf34c160b6761",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9456,
"upload_time": "2024-10-03T19:34:25",
"upload_time_iso_8601": "2024-10-03T19:34:25.861783Z",
"url": "https://files.pythonhosted.org/packages/a5/ee/9496a569da5938717807ce07d456b9e84a6512ce1dc0dface5fcf6bed2b5/dbt_docstring-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8562bbe74393ab32277d5955b41587d55282ff0acdd33ab7055d6119374c6f66",
"md5": "cf5ed1e819d48410032e24234cc4b7e5",
"sha256": "83c5949c8a93205a6ec1d4ee1238eb0e4470a228974180d78cad26e5f9042e98"
},
"downloads": -1,
"filename": "dbt_docstring-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "cf5ed1e819d48410032e24234cc4b7e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8899,
"upload_time": "2024-10-03T19:34:27",
"upload_time_iso_8601": "2024-10-03T19:34:27.150219Z",
"url": "https://files.pythonhosted.org/packages/85/62/bbe74393ab32277d5955b41587d55282ff0acdd33ab7055d6119374c6f66/dbt_docstring-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-03 19:34:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anelendata",
"github_project": "dbt_docstring",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dbt-docstring"
}
JSON
