About documentation
概述¶
良好的dbt模型文档将帮助下游消费者发现和理解您为他们设计的数据集。
dbt提供了一种为dbt项目生成文档并将其呈现为网站的方法。您的项目文档包括：
- 关于项目的信息: 包括模型代码，项目的DAG，测试用例等.
- 关于数据仓库的信息: 包括字段类型，表大小。这些信息是通过对schema查询生成的.
重要的是，dbt还提供了一种将 描述 添加到模型、列、源代码等中的方法，以进一步增强您的文档。
以下是一个示例文档网站:
为你的项目添加说明¶
要向项目添加说明，请在tests的同一目录中使用description:键，如下所示：
version: 2
models:
- name: events
description: This table contains clickstream events from the marketing website
columns:
- name: event_id
description: This is a unique identifier for the event
tests:
- unique
- not_null
- name: user-id
quote: true
description: The user who performed the event
tests:
- not_null
生成项目文档¶
您可以使用CLI为您的项目生成文档站点。
首先，运行dbt docs generate-此命令告诉dbt将有关dbt项目和仓库的相关信息分别编译为manifest.json和catalog.json文件。要查看所有列的文档，而不仅仅是项目中描述的列，请确保您事先使用dbt-run创建了模型。
然后运行dbt docs serve使这些.json文件显示到本地网站上.
使用文档块¶
语法¶
要声明文档块，请使用jinjadocs标记。文档块必须是唯一命名的，并且可以包含任意的标记。在实践中，文档块可能如下所示：
{% docs table_events %}
This table contains clickstream events from the marketing website.
The events in this table are recorded by [Snowplow](http://github.com/snowplow/snowplow) and piped into the warehouse on an hourly basis. The following pages of the marketing site are tracked:
- /
- /about
- /team
- /contact-us
{% enddocs %}
在上面的例子中，一个名为table_events的文档块是用一些描述性的markdown内容定义的。table_events这个名称没有什么意义——只要名称只包含字母数字和下划线字符，你就可以随心所欲地命名文档块。
布局¶
文档块应放置在文件扩展名为.md的文件中。默认情况下，dbt将在所有资源路径中搜索文档块（即模型路径、种子路径、analysis路径、宏路径和快照路径的组合列表）-您可以使用文档路径配置调整此行为。
用法¶
要使用文档块，请使用doc() 函数从schema.yml文件中引用它来代替markdown字符串。使用上面的示例，table_events文档可以包含在schema.yml文件中，如下所示：
version: 2
models:
- name: events
description: '{{ doc("table_events") }}'
columns:
- name: event_id
description: This is a unique identifier for the event
tests:
- unique
- not_null
在生成的文档中, '{{ doc("table_events") }}'将扩展到 table_events文档块中.
设置自定义概述¶
文档网站中显示的“概述”可以通过提供名为__overview__的文档块来覆盖。默认情况下，dbt提供一个概述，其中包含有关文档站点本身的有用信息。根据您的需要，最好使用有关公司风格指南的特定信息、报告链接或联系帮助对象的信息来覆盖此文档块。要覆盖默认概述，请创建一个如下所示的文档块：
{% docs __overview__ %}
# Monthly Recurring Revenue (MRR) playbook.
This dbt project is a worked example to demonstrate how to model subscription
revenue. **Check out the full write-up \[here](https://blog.getdbt.com/modeling-subscription-revenue/),
as well as the repo for this project \[here](https://github.com/dbt-labs/mrr-playbook/).**
...
{% enddocs %}
自定义项目级概述¶
您可以通过创建名为__[project_name]__的文档块，为文档站点中包含的每个dbt项目/包设置不同的概述。例如，为了定义当查看器在dbt_utils或snowplowl包中导航时显示的自定义概述页面：
{% docs __dbt_utils__ %}
# Utility macros
Our dbt project heavily uses this suite of utility macros, especially:
- `surrogate_key`
- `test_equality`
- `pivot`
{% enddocs %}
{% docs __snowplow__ %}
# Snowplow sessionization
Our organization uses this package of transformations to roll Snowplow events
up to page views and sessions.
{% enddocs %}
浏览文档网站¶
使用文档界面，您可以导航到特定模型的文档。这可能看起来像这样：
在这里，您可以看到项目结构的表示、模型的标记描述以及模型中所有列的列表（带有文档）。
在文档页面中，您可以单击网页右下角的绿色按钮来展开DAG的“迷你地图”。此窗格（如下所示）将显示您正在探索的模型的上游和下游。
在本例中，fct_subscription_transactions模型只有一个上游。通过单击窗口右上角的“展开”按钮，我们可以水平旋转图形，并查看我们模型的完整血缘。此血缘可使用--select和--exclude标记进行筛选，这与模型选择语法的语义一致。此外，您可以右键单击与DAG交互，跳转到文档，或与同事共享图形可视化的链接。
部署文档网站¶
安全警告
dbt docs serve命令仅用于文档站点的本地/开发托管。请使用下面列出的方法之一（或类似方法）来确保您的文档网站安全托管！
dbt的文档网站是为了方便在网络上托管而建立的。该网站是“静态”的，这意味着您不需要任何“动态”服务器来为文档提供服务。您可以通过以下几种方式托管文档：