Introduction
In dbt, there are two ways to document your models. The first and easiest way is to do so inside the .yml
file like in one of the acoustic form subtables below:
The other, more sustainable and scalable method is through use of the jinja docs tag. You may have seen this in the structure of the subtables’ schema yml files.
Using the schema_pitfall_trap_sublayer_survey
yml file as an example, the objectid
, globalid
and date_time_details
descriptions have been declared using the doc
function like so:
Setting up the descriptions
The markdown files
All documentation for our dbt work will be found within the docs folder. Inside this folder, there are other subfolders with each subfolder having one or more markdown (.md
) files for each particular Survey123 form. Apart from the subfolders, there are two key markdown (.md
) files: the 1) overview.md
and the references.md
file.
overview.md
This contains the ‘overview’ page of Natural State within the dbt documentation. Consider this as the homepage of Natural State. The overview page is a special page and needs some special syntax.
references.md
This is the file containing documentation for all the field names. Name any field name, eg objectid
, sample_qr_code
, x
and the like and its description will be found inside the references.md
file. We use the jinja tag docs to enclose the description for any field.
The descriptions enclosed inside the docs tag are what will be referenced by the doc function from within our schema yml files. For example, the description for object id
will be referenced by doc(“objectid”).
If all goes well, the description will appear in the deployed dbt website like so:
Form specific subtable descriptions
As earlier mentioned, every form consists of sublayer and/or subtables. For example, the pitfall trap consists 5 subtables. For each subtable, it is also prudent to provide a description for it as this is what external stakeholders will first read before delving into the field descriptions.
For example, if you go to the src/docs/pitfall-trap
folder, you will get the pitfall_trap_ref.md
. Inside this markdown, we have placed the descriptions for all of our five subtable schema files of: 1) schema_pitfall_trap_sublayer_survey.yml
, 2)schema_pitfall_trap_sublayer_grid_location_repeat_deploy.yml
, 3)schema_pitfall_trap_sublayer_grid_location_repeat_retrieve.yml
, 4)schema_pitfall_trap_subtable_repeat_deploy.yml
and 5) schema_pitfall_trap_subtable_repeat_retrieve.yml
. If some subtables are similar in nature, such as those for repeats in the Survey123 form, the descriptions can be reused as we’ve done so for this form.