# dbtdoc
Create dbt document from SQL files
## Install
```
pip install dbtdoc
```
## Features
Currently support document for following
- model
- seed
- common macro and test
- materialization
## Usage
### Prepare
dbtdoc will extract the information from SQL comment block /* */ for each macro and test.
A typical comment block will look like this:
~~~
/*
This information will be used in dbt document.
Information insides dbt block is used to create dbt yml file
```dbt
arguments:
- name: arg01
type: string
description: the first argument
```
* any thing after `dbt` block will be ignored
*/
~~~
By default, every macro, tests will be displayed in dbt document navigator.
Remove item from document by adding following setting.
~~~
/*
this will no be displayed in dbt doc
```dbt
docs:
show: false
```
*/
~~~
### Usage
Default syntax is below:
```
dbtdoc [-h] [-v] [-c] [-b] [-d DOC] [-u] [-o] [-p PREFIX] [-r] [-s SCHEMA] [-S] [-D DEBUG] [-T TARGET]
```
By default `dbtdoc` scans the default DBT project directory (consulting the `DBT_PROJECT_DIR` environment variable if set or the current directory if the environment variable is unset) and all of its sub-folders for sql files, creates 2 file `dbt_schema.yml` and `docs.md` for each folder (the names of the file could be changed by .dbtdoc)
If `dbtdoc` finds a `dbt_project.yml` file in the target folder, it will only scan the folders defined by `model-paths`, `macro-paths`, and `test-paths` in that configuration file.
Parameter `-o` can be used to limit `dbtdoc` to only process the root folder and ignore its sub-folders.
Note: when error happens, use the command with `-D DEBUG` for more details about the errors.
## Configuration
A configuration file `.dbtdoc` is searched in the current folder. A typical configuration file looks like this:
```.dbtdoc
schema_file: "dbt_schema.yml"
doc_file: "docs.md"
quote_string: true
```
If the configuration does not exists, default values are used.
```
SCHEMA_FILE = "dbt_schema.yml"
DOC_FILE = "docs.md"
QUOTE_STRING = False
```
## Other
This project was inspired by [dbt_docstring](https://github.com/anelendata/dbt_docstring).
Raw data
{
"_id": null,
"home_page": "https://github.com/bachng2017/dbtdoc",
"name": "dbtdoc",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "dbt doc sql",
"author": "bachng",
"author_email": "bachng@gmail.com",
"download_url": "",
"platform": null,
"description": "\n\n\n# dbtdoc\nCreate dbt document from SQL files\n\n## Install\n```\npip install dbtdoc\n```\n\n\n\n## Features\nCurrently support document for following\n- model\n- seed\n- common macro and test\n- materialization\n\n## Usage\n\n### Prepare\ndbtdoc will extract the information from SQL comment block /* */ for each macro and test.\n\nA typical comment block will look like this:\n\n~~~\n/*\nThis information will be used in dbt document.\nInformation insides dbt block is used to create dbt yml file \n```dbt\narguments:\n - name: arg01\n type: string\n description: the first argument\n```\n* any thing after `dbt` block will be ignored\n*/\n~~~\n\nBy default, every macro, tests will be displayed in dbt document navigator. \nRemove item from document by adding following setting.\n\n~~~\n/*\nthis will no be displayed in dbt doc\n```dbt\ndocs:\n show: false\n```\n*/\n~~~\n\n### Usage\nDefault syntax is below: \n```\ndbtdoc [-h] [-v] [-c] [-b] [-d DOC] [-u] [-o] [-p PREFIX] [-r] [-s SCHEMA] [-S] [-D DEBUG] [-T TARGET]\n```\n\nBy default `dbtdoc` scans the default DBT project directory (consulting the `DBT_PROJECT_DIR` environment variable if set or the current directory if the environment variable is unset) and all of its sub-folders for sql files, creates 2 file `dbt_schema.yml` and `docs.md` for each folder (the names of the file could be changed by .dbtdoc)\nIf `dbtdoc` finds a `dbt_project.yml` file in the target folder, it will only scan the folders defined by `model-paths`, `macro-paths`, and `test-paths` in that configuration file.\n\nParameter `-o` can be used to limit `dbtdoc` to only process the root folder and ignore its sub-folders.\n\nNote: when error happens, use the command with `-D DEBUG` for more details about the errors.\n\n\n## Configuration\n\nA configuration file `.dbtdoc` is searched in the current folder. A typical configuration file looks like this:\n```.dbtdoc\nschema_file: \"dbt_schema.yml\"\ndoc_file: \"docs.md\"\nquote_string: true\n```\n\nIf the configuration does not exists, default values are used.\n```\nSCHEMA_FILE = \"dbt_schema.yml\"\nDOC_FILE = \"docs.md\"\nQUOTE_STRING = False\n```\n\n## Other\nThis project was inspired by [dbt_docstring](https://github.com/anelendata/dbt_docstring).\n\n\n",
"bugtrack_url": null,
"license": "Apache",
"summary": "Document tool for dbt",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/bachng2017/dbtdoc"
},
"split_keywords": [
"dbt",
"doc",
"sql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ba6bd7a88c2d478dad1d7cd96819201d0d2a37af6eb3b235549d85df05525c66",
"md5": "a9a2f70a9d6859598ccf472d2a7019fa",
"sha256": "e089b4be7b0d1a3645433cd9cf37673da30ebc0f964086611a4ba476e8dc49dd"
},
"downloads": -1,
"filename": "dbtdoc-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a9a2f70a9d6859598ccf472d2a7019fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11602,
"upload_time": "2023-11-05T07:46:37",
"upload_time_iso_8601": "2023-11-05T07:46:37.676380Z",
"url": "https://files.pythonhosted.org/packages/ba/6b/d7a88c2d478dad1d7cd96819201d0d2a37af6eb3b235549d85df05525c66/dbtdoc-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-05 07:46:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bachng2017",
"github_project": "dbtdoc",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dbtdoc"
}
JSON
