Merge pull request #315 from fishtown-analytics/asset-paths

Write docs on asset-paths

website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md

@@ -45,3 +45,4 @@ Please be aware of the following changes in v0.18.0. While breaking, we do not e
 - [model selection syntax](model-selection-syntax)
 - [list (ls)](commands/list)
 - [Redshift profile](redshift-profile#specifying-an-iam-profile)
+- [`asset-paths` config](asset-paths) (also updated [dbt_project.yml](dbt_project.yml.md) and the [description](description) docs to match)

website/docs/reference/dbt_project.yml.md

@@ -23,6 +23,7 @@ dbt uses YAML in a few different places. If you're new to YAML, it would be wort
 [macro-paths](project-configs/macro-paths): [directorypath]
 [snapshot-paths](project-configs/snapshot-paths): [directorypath]
 [docs-paths](project-configs/docs-paths): [directorypath]
+[asset-paths](project-configs/asset-paths): [directorypath]
 
 [target-path](project-configs/target-path): directorypath
 [log-path](project-configs/log-path): directorypath

website/docs/reference/project-configs/asset-paths.md

@@ -0,0 +1,39 @@
+---
+datatype: [directorypath]
+default_value: []
+---
+
+<File name='dbt_project.yml'>
+
+```yml
+asset-paths: [directorypath]
+```
+
+</File>
+
+## Definition
+Optionally specify a custom list of directories to copy to the `target` directory as part of the `docs generate` command. This is useful for rendering images in your repository in your project documentation.
+
+<Changelog>
+
+* `v0.18.0`: This configuration was introduced — see the [migration guide for 0.18.0](upgrading-to-0-18-0) for more details.
+
+</Changelog>
+
+## Default
+By default, dbt will not compile any additional files as part of `docs generate`, i.e. `analysis-paths: []`
+
+## Examples
+### Compile files in the `assets` subdirectory as part of `docs generate`
+
+<File name='dbt_project.yml'>
+
+```yml
+asset-paths: ["assets"]
+```
+
+</File>
+
+Any files included in this directory will be copied to the `target/` directory as part of `dbt docs generate`, making them accessible as images in your project documentation.
+
+Check out the full writeup on including images in your descriptions [here](/reference/resource-properties/description/#include-an-image-from-your-repo-in-your-descriptions).

website/docs/reference/resource-properties/description.md

@@ -292,7 +292,7 @@ You can use relative links to link to another model. It's a little hacky — but
 version: 2
 
 models:
-  - name: dim_customers
+  - name: customers
     description: "Filtering done based on \[stg_stripe__payments](#!/model/model.jaffle_shop.stg_stripe__payments)"
 
     columns:
@@ -304,20 +304,60 @@ models:
 </File>
 
 
-### Include an image in your descriptions
+### Include an image from your repo in your descriptions
+To include an image from your repository in your descriptions:
+1. Add the file in a subdirectory, e.g. `assets/dbt-logo.png`
+2. Set the [`asset-paths` config](project-configs/asset-paths) in your `dbt_project.yml` file so that this directory gets copied to the `target/` directory as part of `dbt docs generate`
+
+<File name='dbt_project.yml'>
+
+```yml
+asset-paths: ["assets"]
+```
 
-At present, it's not possible to include an image in your project and render it as part of your project documentation using the image path. This is because images are not included in the `target` directory when you execute `dbt compile`. We hope to address this in the future ([related issue](https://github.com/fishtown-analytics/dbt/issues/2072)).
+</File>
 
-Instead, consider hosting the image online and using the image URL to render the image.
+2. Use a Markdown link to the image in your `description:`
 
 <File name='models/schema.yml'>
 
 ```yml
 version: 2
 
 models:
-  - name: dim_customers
-    description: "!\[dbt Logo](https://github.com/fishtown-analytics/dbt/raw/master/etc/dbt-horizontal.png)"
+  - name: customers
+    description: "!\[dbt Logo](assets/dbt-logo.png)"
+
+    columns:
+      - name: customer_id
+        description: Primary key
+
+```
+
+</File>
+
+_[CLI users only]_
+
+3. Run `dbt docs generate` — the `assets` directory will be copied to the `target` directory
+
+4. Run `dbt docs serve` — the image will be rendered as part of your project documentation:
+
+<Lightbox src="/img/reference/image-in-docs.png" title="The image at assets/dbt-logo.png is rendered correctly"/>
+
+If mixing images and text together, also consider using a docs block.
+
+### Include an image from the web in your descriptions
+
+Use the image URL to render the image.
+
+<File name='models/schema.yml'>
+
+```yml
+version: 2
+
+models:
+  - name: customers
+    description: "!\[dbt Logo](https://raw.githubusercontent.com/fishtown-analytics/dbt/dev/marian-anderson/etc/dbt-logo-full.svg)"
 
     columns:
       - name: customer_id
@@ -327,4 +367,4 @@ models:
 
 </File>
 
-If mixing images and text together, consider using a docs block instead.
+If mixing images and text together, also consider using a docs block.

website/sidebars.js

@@ -204,6 +204,7 @@ module.exports = {
           label: "Project configurations",
           items: [
             "reference/project-configs/analysis-paths",
+            "reference/project-configs/asset-paths",
             "reference/project-configs/clean-targets",
             "reference/project-configs/config-version",
             "reference/project-configs/data-paths",