Only render jinja inside of docs blocks in .md files

[foundinblank]

Issue

Issue description

When Jinja code exists in a README file, such as {{ ref(table_name) }}, dbt attempts to run it and returns a cryptic Encountered an error: 'ref' is undefined error.

Results

Error is thrown due to Jinja code in README files. Normally I'd have expected dbt to ignore code in README files.

System information

The output of dbt --version:

installed version: 0.11.0
   latest version: 0.11.0

The operating system you're running on: OSX 10.13.6

The python version you're using (probably the output of python --version): Python 3.5.4

Steps to reproduce

A regular README.md file, e.g.,

# dbt Models
Models can be referenced in dbt using {{ ref(table_name) }} and cool things happen.

dbt will attempt to run ref(table_name).

[foundinblank]

If you want to keep the ref() code in your README file, you can enclose the code block like this

{% raw %}
 ...code... 
{% endraw %}

not elegant but works

[drewbanin]

hey @foundinblank - thanks for the report! So, these .md files are indeed parsed by dbt as jinja code. It's the mechanism by which the {% docs %} blocks work! You're definitely correct in identifying that ref() is undefined in the docs block context, however.

I think we should use this issue to describe the context available in docs blocks, which is currently not defined anywhere.

[alanmcruickshank]

I don't mind taking a crack at this at some point. We're working on our documentation so it could be useful. @drewbanin it could be useful for the ref() function to still resolve to a table name in a markdown context. Can you think of a reason for not doing that?

[drewbanin]

@alanmcruickshank that sounds like a good idea to me!

[drewbanin]

I think I misunderstood this issue when I first commented on it!

Two things are true:

1. we should expand/document the context available inside of docs blocks
2. dbt should not render jinja code located outside of docs blocks

So, something like:

# dbt Models
Models can be referenced in dbt using {{ ref(table_name) }} and cool things happen.

should be rendered exactly as written.

Something else like:

# dbt Models
Models can be referenced in dbt using {{ ref(table_name) }} and cool things happen.
{% docs my_docs %}

   {{ my_macro(...) }}

{% enddocs %}

should be rendered with some well-defined context. TBD if this makes it into the Wilt Chamberlain milestone, but if not, we'll slip it in for the next one!