Ensure Macros for Documentation Are Inherited Instead of Rendered

[HampB]

Hey,

First off—this is a really nice project that saves a lot of headaches! Thanks for all the work on it.

Issue / Feature Request

When macros are used to generate documentation, the inherited documentation is currently stored as the rendered result. Ideally, downstream models should inherit the doc macro itself so that any updates made in the docs.md file apply consistently to all models.

Problem

Right now, if you update the documentation, inconsistencies can occur because the rendered version is inherited rather than the macro itself. This means changes made in the docs.md file do not propagate correctly to downstream models.
Upstream:

Downstream:

Suggested Solution

Instead of inheriting the rendered result, allow the doc macro to be passed down so updates in the docs.md file apply to all models.

Additional Context

• Running with --force-inherit-descriptions, as there might be documentation changes that should not be overwritten.
• This would help maintain consistency across documentation updates.

Would love to hear your thoughts on this!

[ryanvolpi]

+1 to the above. What is worse is that I am finding that the yaml refactor command is also replacing the original doc invocation with the rendered version. It seems that dbt-osmosis is incompatible with doc blocks in the current state.

[HampB]

I just discovered, thanks to issue #219, that the --use-unrendered-descriptions option exists. I haven't tried it yet, but it seems to address the issue discussed here.

If that's the case, we should consider updating the documentation website to include all CLI options available via --help.

[rognerud]

This is actually a more generalized issue than doc blocks. Osmosis tries to render any jinja {{}} syntax in any part of the yaml when running.