Reference macros in YAML docs _without_ calling them

Help
1

The problem I’m having

One of the awesome parts about the YAML files is that they can resolve Jinja macros, but is there a way to write them without calling them?

I’m documenting one of my macros in a macros YAML block which expects a relation as one of its arguments, but using the ref inside the documentation is throwing a compilation error because it can’t resolve the ref macro in the YAML file

The context of why I’m trying to do this

For an MWE, consider some silly macro like:

{# silly_example.sql #}

{% macro silly_example(rel) %}
    select * from {{ rel }}
{% endmacro %}

I’m documenting this in a YAML file:

---
version: 2

macros:
  - name: silly_example
    description: An MWE for my example.
    arguments:
      - name: relation
        type: str | Relation
        description: >
          The relation to select from.

          Example usage:
          ```
          WITH example_cte AS (
              {{ silly_example( ref("my_model") ) }}
          )
          ```

However, when I compile the documentation I get the following compile error:

Compilation Error
  'ref' is undefined. This can happen when calling a macro that does not exist.

This is because the YAML file is trying to resolve the ref macro used in the macro’s description

What I’ve already tried

I can just remove the code block in the description and the project will go back to compiling fine, but I like to include examples like this in my docs (any time I write code, not just dbt) to give an example to the user of how my classes/functions are intended to be used

I’ve tried swapping ref out for something silly like _ref instead, but it still tries to then call the _ref macro and gives the same compile error (complaining about _ref instead)

2

I am getting the same error as well even with a single macro. New to this so not sure how to resovle it.