Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding a description for singular data tests and custom generic data tests #6193

Open
1 task done
dbeatty10 opened this issue Oct 1, 2024 · 0 comments
Open
1 task done
Labels
content Improvements or additions to content improvement Use this when an area of the docs needs improvement as it's currently unclear

Comments

@dbeatty10
Copy link
Contributor

dbeatty10 commented Oct 1, 2024

Contributions

  • I have read the contribution docs, and understand what's expected of me.

Link to the page on docs.getdbt.com requiring updates

Not sure exactly which pages -- something to determine based on the content below!

What part(s) of the page would you like to see updated?

Make sure there's an explanation in one or more places how to:

  • add descriptions for definitions of custom generic data tests
  • add descriptions for instances of singular data tests

Overview

There are two types of data tests:

  1. Generic
  2. Singular

We have two issues for adding description to data tests:

  1. Allow instances of generic data tests to be documented dbt-core#2578
  2. [CT-3323] Allow singular tests to be documented dbt-core#9005 (comment)

A major difference between custom generic data tests and singular data tests is that the former can be re-used, but the latter can't.

So there are really three ways we could potentially add a description to data tests:

  1. Definitions of generic data tests
  2. Instances of generic data tests
  3. Instances of singular data tests

(There's not a 4th option because there's only one instance per definition of a singular data test.)

Details

Generic data tests have one macro definition and then zero to many instances where they are used. So that's two different places we can imagine adding a description for generic data tests.

However, for singular data tests, there's one instance for each definition -- they are one-to-one. So there's only one description possible for that type of data test.

Descriptions for reusable definitions of generic data tests

Since the definition is just a macro, the definition of a custom generic data test can already have a description like this:

macros:
  - name: test_CUSTOM_GENERIC_TEST_NAME
    description: markdown_string
    arguments:
      - name: argument_name
        description: markdown_string

Descriptions for instances of generic data tests

However, I don't believe the instances of generic data tests can be documented until dbt-labs/dbt-core#2578 is implemented.

Descriptions for singular data tests

Added in dbt-labs/dbt-core#10792 to resolve dbt-labs/dbt-core#9005!

Additional information

See #5631 and #6191 for related issues.

@dbeatty10 dbeatty10 added content Improvements or additions to content improvement Use this when an area of the docs needs improvement as it's currently unclear labels Oct 1, 2024
dbeatty10 added a commit that referenced this issue Oct 1, 2024
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 <[email protected]>
Co-authored-by: nataliefiann <[email protected]>
Co-authored-by: Mirna Wong <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
content Improvements or additions to content improvement Use this when an area of the docs needs improvement as it's currently unclear
Projects
None yet
Development

No branches or pull requests

1 participant