Перейти к основному содержимому

О функции doc

Текст документации можно определить в блоке docs и переиспользовать в полях описаний через функцию Jinja doc(). Она доступна только в YAML-файлах свойств ресурсов с полем описания, например моделей, столбцов моделей, источников, таблиц и столбцов источников.

Как и ref(), функция Jinja doc() ищет объект по имени. В данном случае она находит блок docs, например {% docs orders %} ... {% enddocs %} в файле docs.md, и возвращает его обработанное содержимое. См. Руководство по документации.

Использование​

В dbt описания столбцов можно задать прямо в YAML-файле свойств модели. Описание задаётся обычным текстом и относится к конкретному столбцу.

Добавление описаний вручную​

models/orders.yml
models:
- name: orders
columns:
- name: order_total_cents
description: "Total order amount in cents. This value is always a positive integer and excludes taxes and shipping."

Когда вы запускаете dbt docs generate и открываете сайт документации, этот текст отображается в точности так, как он написан, но только для столбца order_total_cents модели orders.

Повторное использование описаний с помощью doc()​

Чтобы не повторять одно и то же описание для нескольких моделей или столбцов, dbt позволяет определять документацию отдельно и ссылаться на неё с помощью функции doc().

При таком подходе документация пишется один раз в markdown-файле в именованном блоке docs, а затем используется повторно везде, где это необходимо в проекте. Это помогает обеспечить согласованность и упрощает поддержку общих определений с течением времени.

Сначала определите блок документации для повторного использования в файле docs.md:

models/docs/example.md
{% docs order_total_cents %}
Общая сумма заказа в центах. Это значение всегда является положительным целым числом и не включает налоги и стоимость доставки.
{% enddocs %}

Так определяется блок docs с именем order_total_cents. Ссылайтесь на него с помощью doc('order_total_cents') в полях описания везде, где нужен тот же текст.

Затем добавьте ссылку на эту документацию в YAML-файл свойств:

models/orders.yml
models:
- name: orders
columns:
- name: order_total_cents
description: "{{ doc('order_total_cents') }}"

Когда вы запускаете dbt docs generate, dbt разрешает ссылку doc(), находя соответствующий блок docs и вставляя его содержимое в сгенерированную документацию.

В результате в описании столбца отображается текст, заданный в markdown-файле, а не непосредственно в YAML.

Избегайте повторяющихся имён​

Имена блоков docs должны быть уникальными в пределах проекта. Если вы определяете несколько блоков {% docs %} с одинаковым именем, dbt не может однозначно определить, какой блок использовать при вызове doc('DOCS_BLOCK_NAME').

(Версии dbt: v2.0 и новее)

В dbt v2 повторяющиеся имена блоков docs не допускаются. При обнаружении дубликатов dbt указывает конфликтующие файлы и выводит предупреждение. Переименуйте один из блоков, чтобы имя каждого блока docs было уникальным. Подробнее см. в разделе Более строгая проверка повторяющихся блоков docs.

models/docs/example.md
{% docs order_total_cents %}
Общая сумма заказа в центах. Это значение всегда является положительным целым числом и не включает налоги и стоимость доставки.
{% enddocs %}

{% docs order_total_cents %}
Общая сумма заказа в центах без учёта налогов и платы за доставку.
{% enddocs %}
dbt found two docs with the same name: 'order_total_cents' in files: 'models/docs/example.md' and 'models/docs/example.md'

Нашли ошибку?

0
Loading