Documentation editor does not handle docs blocks

[geo909]

Expected behavior

Docs blocks is jinja code for reusable documentation, which can be extremely useful in some cases. Unfortunately, the Documentation Editor does not play well with it in the following sense:

When using the documentation editor to add/modify any description for a model, saving the documentation will overwrite all existing docs blocks in the documentation yaml file and replace them with the compiled documentation. This is regardless of whether the modified documentation was originally a docs block.

Actual behavior

There should be no overwrites of doc blocks when saving documentation in the power user's documentation editor.

Ideally, a more holistic approach would be to actually support doc blocks natively. I am not sure how this would look like to be honest. I would be happy to think about it and propose ideas if that would help.

Steps To Reproduce

First, create the following files:

-- example.sql
select
    "foo" as column_1,
    "bar" as column_2,
    "baz" as column_3,
    "qux" as column_4

# docs.md
{% docs generic_column_description %}
    This is an example doc block that can be reused in multiple descriptions.
{% enddocs %}

# models.yml
models:
  - name: example
    description: My model description
    columns:
      - name: column_1
        description: This is my column 1
      - name: column_2
        description: This is my column 2
      - name: column_3
        description: >
          {{ doc('generic_column_description') }}
      - name: column_4
        description: |
          {{ doc('generic_column_description') }}

Then

1. Run dbt docs generate
2. Navigate to example.sql in VS Code
3. Open the Documentation Editor, change the description of column_1 and save.

Now all docs blocks are removed from models.yml:

models:
  - name: example
    description: My model description
    columns:
      - name: column_1
        description: Hello there
      - name: column_2
        description: This is my column 2
      - name: column_3
        description: This is an example doc block that can be reused in multiple
          descriptions.
      - name: column_4
        description: This is an example doc block that can be reused in multiple
          descriptions.

Log output/Screenshots

No response

Operating System

Ubuntu 22.04

dbt version

1.5.2

dbt Adapter

Big query 1.5.3

dbt Power User version

0.25.2

Are you willing to submit PR?

• [ ] Yes I am willing to submit a PR!

[septponf]

Anything planned to handle this? Would be great.