Updated singular tests section to show they can now be documented

website/docs/docs/build/data-tests.md

@@ -68,8 +68,33 @@ having total_amount < 0
 
 The name of this test is the name of the file: `assert_total_payment_amount_is_positive`. Simple enough.
 
-Singular data tests are easy to write—so easy that you may find yourself writing the same basic structure over and over, only changing the name of a column or model. By that point, the test isn't so singular! In that case, we recommend...
+Singular data tests are easy to write—so easy that you may find yourself writing the same basic structure over and over, only changing the name of a column or model. By that point, the test isn't so singular! In that case, we recommend [generic data tests](#generic-data-tests).
 
+### Document singular data tests
+
+<VersionBlock firstVersion="1.9">
+
+The top-level `data_tests:` key in YAML files allows for adding a [`description`](/reference/resource-properties/description) for singular data tests. Descriptions can include Markdown, as well as the [`doc` jinja function](/reference/dbt-jinja-functions/doc).
+
+<File name='tests/singular/data_tests.yml'>
+
+```yml
+
+# top-level
+data_tests:
+  - name: my_super_cool_singular_test
+    description: The `order_id` is unique for every row in the orders model
+```
+
+</File>
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+
+The `description` property is available for [singular data tests](/build/data-tests#singular-data-tests) beginning in dbt v1.9.
+
+</VersionBlock>
 
 
 ## Generic data tests

website/docs/docs/build/documentation.md

@@ -101,8 +101,19 @@ 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
+
+<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 (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), [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.
+
+</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 (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>
+
 
 ### Usage
 To use a docs block, reference it from your `schema.yml` file with the [doc()](/reference/dbt-jinja-functions/doc) function in place of a markdown string. Using the examples above, the `table_events` docs can be included in the `schema.yml` file as shown below:

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
+
+<VersionBlock firstVersion="1.9">
+
+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), [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](/build/data-tests#singular-data-tests) beginning in dbt v1.9.
+
+</VersionBlock>
+
+</TabItem>
+
 
 </Tabs>