Skip to content

Commit

Permalink
Singular data tests can now be documented (#6191)
Browse files Browse the repository at this point in the history
Resolves #6132
Originally #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 #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 dbt-labs/dbt-core#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 <Natalie.Fiann@dbtlabs.com>
Co-authored-by: nataliefiann <120089939+nataliefiann@users.noreply.github.com>
Co-authored-by: Mirna Wong <89008547+mirnawong1@users.noreply.github.com>
  • Loading branch information
4 people authored Oct 1, 2024
1 parent 364da5b commit 2d9838c
Show file tree
Hide file tree
Showing 3 changed files with 51 additions and 2 deletions.
13 changes: 12 additions & 1 deletion website/docs/docs/build/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<VersionBlock firstVersion="1.9">

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)) &mdash; you can adjust this behavior using the [docs-paths](/reference/project-configs/docs-paths) config.

</VersionBlock>

<VersionBlock lastVersion="1.8">

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)) &mdash; you can adjust this behavior using the [docs-paths](/reference/project-configs/docs-paths) config.

</VersionBlock>


### Usage
Expand Down
12 changes: 11 additions & 1 deletion website/docs/reference/project-configs/docs-paths.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
<VersionBlock firstVersion="1.9">
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.
</VersionBlock>
<VersionBlock lastVersion="1.8">
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.
</VersionBlock>
## Example
Expand Down
28 changes: 28 additions & 0 deletions website/docs/reference/resource-properties/description.md
Original file line number Diff line number Diff line change
Expand Up @@ -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', },
]
}>
<TabItem value="models">
Expand Down Expand Up @@ -145,6 +146,33 @@ macros:

</TabItem>

<TabItem value="singular_data_tests">

<VersionBlock firstVersion="1.9">

<File name='tests/singular/schema.yml'>

```yml
version: 2

data_tests:
- name: singular_data_test_name
description: markdown_string

```

</File>

</VersionBlock>

<VersionBlock lastVersion="1.8">

The `description` property is available for singular data tests beginning in dbt v1.9.

</VersionBlock>

</TabItem>


</Tabs>

Expand Down

0 comments on commit 2d9838c

Please sign in to comment.