# О функции doc

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

Как и `ref()`, функция Jinja `doc()` ищет объект по имени. В данном случае она находит блок docs, например `{% docs orders %} ... {% enddocs %}` в файле `docs.md`, и возвращает его обработанное содержимое. См. [Руководство по документации](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md).

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

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

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

models/orders.yml

```yaml
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

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

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

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

models/orders.yml

```yaml
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](https://docs.getdbt.tech/docs/dbt-versions/dbt-upgrade/upgrading-to-v2.md?version=2.0#stricter-evaluation-of-duplicate-docs-blocks).

models/docs/example.md

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

```text
dbt found two docs with the same name: 'order_total_cents' in files: 'models/docs/example.md' and 'models/docs/example.md'
```
