Just wanted to share a small trick that I don’t see documented elsewhere. I’ve found it super helpful for keeping my docs DRY.
If you have a special note/item that you want to include in the documentation for multiple sources/models/columns/tests, you can create a separate docs block and reference it in the relevant description property in your schema.yml file.
For example, I want to put the same warning on all models that relate to Users in our main webapp.
- I’ll create a docs block with just the warning in it. (Lets call it
user_related_model_warning.)- I like to put each of these in a separate file in the docs folder, and preface them with an underscore, to keep them sorted at the top and separate from the “regular” docs, but this is just a personal preference.
- I’ll create all of my regular docs. Let’s say I want to put this warning in front of the docs for the
users_referralmodel, anusers_authmodel, andusers_sessionmodel. - Now, I can prepend or append the warning doc block to the regular doc, by adding it in the description property in my schema.yml file. My users_schema.yml file will look something like this:
models:
...
- name: users_referral
description: >
'{{ doc("user_related_model_warning") }}'
'{{ doc("users_referral") }}'
...
- name: users_auth
description: >
'{{ doc("user_related_model_warning") }}'
'{{ doc("users_auth") }}'
...
- name: users_session
description: >
'{{ doc("user_related_model_warning") }}'
'{{ doc("users_session") }}'
The resulting generated docs will contain the content of the user_related_model_warning doc, then a newline, then the content of the regular doc.
As far as I can tell, there’s currently no way to include a docs block in the middle of another doc. You can only put one docs block before or after another one.
Curious to hear if anyone else has any other solutions, suggestions, etc! How do you handle this kind of thing?
