From 2d9838c5e0624f04a09cebfe044a559d12735ac2 Mon Sep 17 00:00:00 2001 From: Doug Beatty <44704949+dbeatty10@users.noreply.github.com> Date: Tue, 1 Oct 2024 09:45:25 -0600 Subject: [PATCH] Singular data tests can now be documented (#6191) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves https://github.com/dbt-labs/docs.getdbt.com/issues/6132 Originally https://github.com/dbt-labs/docs.getdbt.com/pull/6147 ## What are you changing in this pull request and why? The `description` property is available for singular data tests beginning in dbt v1.9, and this PR highlights how singular tests can now be documented. ### 🎩 Previews - [`description`](https://docs-getdbt-com-git-dbeatty-6132-docs-dbt-labs.vercel.app/reference/resource-properties/description) - [`docs-paths`](https://docs-getdbt-com-git-dbeatty-6132-docs-dbt-labs.vercel.app/reference/project-configs/docs-paths) - [documentation placement](https://docs-getdbt-com-git-dbeatty-6132-docs-dbt-labs.vercel.app/docs/build/documentation#placement) ### Additional information Opened https://github.com/dbt-labs/docs.getdbt.com/issues/6193 since we don't have documentation how to add a `description` for the Jinja macro associated with custom generic tests. This follow-up will allow us to consider the `description` of both generic and singular data tests in context of each other. ## Checklist - [x] I have reviewed the [Content style guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md) so my content adheres to these guidelines. - [x] The topic I'm writing about is for specific dbt version(s) and I have versioned it according to the [version a whole page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version) and/or [version a block of content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content) guidelines. - [x] Wait until https://github.com/dbt-labs/dbt-core/pull/10792 is merged - [x] Add a note to the prerelease version [Migration Guide](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/docs/docs/dbt-versions/core-upgrade) --------- Co-authored-by: Natalie Fiann Co-authored-by: nataliefiann <120089939+nataliefiann@users.noreply.github.com> Co-authored-by: Mirna Wong <89008547+mirnawong1@users.noreply.github.com> --- website/docs/docs/build/documentation.md | 13 ++++++++- .../reference/project-configs/docs-paths.md | 12 +++++++- .../resource-properties/description.md | 28 +++++++++++++++++++ 3 files changed, 51 insertions(+), 2 deletions(-) diff --git a/website/docs/docs/build/documentation.md b/website/docs/docs/build/documentation.md index d040d3c5bef..6f7c6c27f31 100644 --- a/website/docs/docs/build/documentation.md +++ b/website/docs/docs/build/documentation.md @@ -101,7 +101,18 @@ The events in this table are recorded by [Snowplow](http://github.com/snowplow/s In the above example, a docs block named `table_events` is defined with some descriptive markdown contents. There is nothing significant about the name `table_events` — docs blocks can be named however you like, as long as the name only contains alphanumeric and underscore characters and does not start with a numeric character. ### Placement -Docs blocks should be placed in files with a `.md` file extension. By default, dbt will search in all resource paths for docs blocks (i.e. the combined list of [model-paths](/reference/project-configs/model-paths), [seed-paths](/reference/project-configs/seed-paths), [analysis-paths](/reference/project-configs/analysis-paths), [macro-paths](/reference/project-configs/macro-paths) and [snapshot-paths](/reference/project-configs/snapshot-paths)) — you can adjust this behavior using the [docs-paths](/reference/project-configs/docs-paths) config. + + + +Docs blocks should be placed in files with a `.md` file extension. By default, dbt will search in all resource paths for docs blocks (for example, the combined list of [model-paths](/reference/project-configs/model-paths), [seed-paths](/reference/project-configs/seed-paths), [analysis-paths](/reference/project-configs/analysis-paths), [test-paths](/reference/project-configs/test-paths), [macro-paths](/reference/project-configs/macro-paths), and [snapshot-paths](/reference/project-configs/snapshot-paths)) — you can adjust this behavior using the [docs-paths](/reference/project-configs/docs-paths) config. + + + + + +Docs blocks should be placed in files with a `.md` file extension. By default, dbt will search in all resource paths for docs blocks (for example, the combined list of [model-paths](/reference/project-configs/model-paths), [seed-paths](/reference/project-configs/seed-paths), [analysis-paths](/reference/project-configs/analysis-paths), [macro-paths](/reference/project-configs/macro-paths), and [snapshot-paths](/reference/project-configs/snapshot-paths)) — you can adjust this behavior using the [docs-paths](/reference/project-configs/docs-paths) config. + + ### Usage diff --git a/website/docs/reference/project-configs/docs-paths.md b/website/docs/reference/project-configs/docs-paths.md index 51ff5c5ccca..5481c19c9fd 100644 --- a/website/docs/reference/project-configs/docs-paths.md +++ b/website/docs/reference/project-configs/docs-paths.md @@ -17,8 +17,18 @@ Optionally specify a custom list of directories where [docs blocks](/docs/build/ ## Default -By default, dbt will search in all resource paths for docs blocks (i.e. the combined list of [model-paths](/reference/project-configs/model-paths), [seed-paths](/reference/project-configs/seed-paths), [analysis-paths](/reference/project-configs/analysis-paths), [macro-paths](/reference/project-configs/macro-paths) and [snapshot-paths](/reference/project-configs/snapshot-paths)). If this option is configured, dbt will _only_ look in the specified directory for docs blocks. + + +By default, dbt will search in all resource paths for docs blocks (for example, the combined list of [model-paths](/reference/project-configs/model-paths), [seed-paths](/reference/project-configs/seed-paths), [analysis-paths](/reference/project-configs/analysis-paths), [test-paths](/reference/project-configs/test-paths), [macro-paths](/reference/project-configs/macro-paths), and [snapshot-paths](/reference/project-configs/snapshot-paths)). If this option is configured, dbt will _only_ look in the specified directory for docs blocks. + + + + + +By default, dbt will search in all resource paths for docs blocks (i.e. the combined list of [model-paths](/reference/project-configs/model-paths), [seed-paths](/reference/project-configs/seed-paths), [analysis-paths](/reference/project-configs/analysis-paths), [macro-paths](/reference/project-configs/macro-paths), and [snapshot-paths](/reference/project-configs/snapshot-paths)). If this option is configured, dbt will _only_ look in the specified directory for docs blocks. + + ## Example diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md index 59420614b02..6f32f75efa4 100644 --- a/website/docs/reference/resource-properties/description.md +++ b/website/docs/reference/resource-properties/description.md @@ -13,6 +13,7 @@ description: "This guide explains how to use the description key to add YAML des { label: 'Snapshots', value: 'snapshots', }, { label: 'Analyses', value: 'analyses', }, { label: 'Macros', value: 'macros', }, + { label: 'Singular data tests', value: 'singular_data_tests', }, ] }> @@ -145,6 +146,33 @@ macros: + + + + + + +```yml +version: 2 + +data_tests: + - name: singular_data_test_name + description: markdown_string + +``` + + + + + + + +The `description` property is available for singular data tests beginning in dbt v1.9. + + + + +