# Сборка и просмотр документации с помощью dbt

Платформа dbt

dbt позволяет генерировать документацию для вашего проекта и платформы данных. Документация автоматически обновляется с учётом новой информации после полностью успешного выполнения задания, что обеспечивает её точность и актуальность.

По умолчанию для работы с документацией в dbt используется [Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md), доступный на [тарифных планах Starter, Enterprise или Enterprise+](https://www.getdbt.com/pricing/). Используйте [Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md), чтобы просматривать ресурсы проекта (например, модели, тесты и метрики) и связи между ними и лучше понимать текущее состояние проекта в производственной среде.

Обратитесь к [документации](https://docs.getdbt.tech/docs/build/documentation.md) для получения более подробной информации о конфигурации.

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

Чтобы создать статический сайт документации для размещения на собственной инфраструктуре, используйте [dbt Docs v2](https://docs.getdbt.tech/docs/build/view-documentation.md#dbt-docs-v2) локально. dbt Docs v2 недоступен в dbt platform.

## Настройка задания для документации

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

Catalog использует [метаданные](https://docs.getdbt.tech/docs/explore/explore-projects.md#generate-metadata) каждого запуска задания в вашей продакшен-среде или среде предварительного тестирования (staging). Задания, выполняемые на v2, автоматически генерируют эти метаданные при каждом запуске, поэтому отдельное задание для документации, шаг `dbt docs generate` или флажок генерации документации не нужны.

Чтобы поддерживать Catalog в актуальном состоянии:

1. В левом верхнем углу нажмите **Deploy** и выберите **Jobs**.
2. Создайте новое задание или выберите существующее задание в продакшен-среде или среде staging и нажмите **Settings**.
3. В разделе **Execution settings** добавьте команды, которые хотите выполнить, например `dbt build`, и нажмите **Save**.
4. После выполнения задания нажмите **Catalog** в меню навигации, чтобы изучить свой проект.

Если вы добавите `dbt docs generate` в качестве шага выполнения, dbt вместо этого выполнит `dbt compile --write-catalog` и отобразит баннер, направляющий вас в Catalog. Подробнее см. в разделе [Поведение платформы](https://docs.getdbt.tech/reference/commands/cmd-docs.md?version=2#dbt-platform-behavior).

Задания только для обновления метаданных

Чтобы обновить метаданные Catalog без построения моделей, добавьте `dbt compile --write-catalog` в раздел **Commands**.

## Просмотр документации проекта

[Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md) — это место для просмотра документации вашего проекта в dbt platform. Здесь всегда отображается последнее состояние проекта в продакшене, поэтому вам не нужно ничего развёртывать или размещать на хостинге. В Catalog вы можете:

* Искать и фильтровать ресурсы проекта, такие как модели, источники и метрики.
* Изучать [граф зависимостей](https://docs.getdbt.tech/docs/explore/explore-projects.md#project-lineage), чтобы видеть связи между ресурсами.
* Открывать [сведения о ресурсе](https://docs.getdbt.tech/docs/explore/explore-projects.md#view-resource-details), чтобы просматривать его описание, столбцы, тесты и результаты последних запусков.

Чтобы открыть его, нажмите **Catalog** в меню навигации. Чтобы изучить модель на графе зависимостей, выберите свой проект на левой боковой панели, нажмите **View lineage**, а затем нажмите на модель, чтобы просмотреть её описание.

[![Пример полного графа зависимостей в Catalog](/img/docs/collaborate/dbt-explorer/example-project-lineage-graph.png?v=2 "Пример полного графа зависимостей в Catalog")](#)Пример полного графа зависимостей в Catalog

Catalog доступен пользователям с правами Developer и пользователям с доступом только для чтения. Чтобы поделиться проектом с заинтересованными сторонами, которые не занимаются разработкой в dbt, предоставьте всем соответствующим пользователям [доступ только для чтения](https://docs.getdbt.tech/docs/platform/manage-access/seats-and-users.md) к Catalog без ограничений.

## Связанная документация

* [Документация](https://docs.getdbt.tech/docs/build/documentation.md)
* [Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md)