Singular data tests can now be documented (#6191)

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>

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.
+
+<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

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.
 
+<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
 

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', },
   ]
 }>
 <TabItem value="models">
@@ -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>