docs: adds DBT concept documentation

[pomegranited]

Description

1. Adds dbt concept documentation
2. Updates the dbt extension how-to

Supporting information

Closes #68

[openedx-webhooks]

Thanks for the pull request, @pomegranited! Please note that it may take us up to several weeks or months to complete a review and merge your PR.

Feel free to add as much of the following information to the ticket as you can:

• supporting documentation
• Open edX discussion forum threads
• timeline information ("this must be merged by XX date", and why that is)
• partner information ("this is a course on edx.org")
• any other information that can help Product understand the context for the PR

All technical communication about the code itself will be done via the GitHub pull request interface. As a reminder, our process documentation is here.

Please let us know once your PR is ready for our review and all tests are green.

[bmtcril]

nit: ddt -> dbt

[bmtcril]

I think the preferred way to customize dbt is to change the DBT_REPOSITORY / DBT_BRANCH / DBT_REPOSITORY_PATH to your dbt project, and have that project make our dbt package a requirement. Is that you how you did it @Ian2012 ?

[Ian2012]

Yes, you can update it to point to the main branch (to be always up to date) but it's better to have a pinned version so we don't introduce breaking changes

[pomegranited]

Oh interesting, I thought that EXTRA_DBT_PACKAGES was for adding custom dbt packages, rather than encouraging people to fork aspects-dbt or run with a different version?

Let me know which way it should read, and I'll update the recommendations here.

[Ian2012]

No, EXTRA_DBT_PACKAGES is a list of python requirement that will be installed before your custom version of aspects-dbt will be run.

While, you can change your DBT_REPOSITORY and create a little packages.yml with aspects-dbt as a package. This will allow you to have all the base functionality of aspects while creating your custom models without forking. See this commit for an example

[pomegranited]

Oh cool, thank you for these details @Ian2012 ! I'll incorporate them here.

[pomegranited]

How's this? https://docsopenedxorg--111.org.readthedocs.build/projects/openedx-aspects/en/111/how-tos/dbt_extensions.html

[Ian2012]

Great, just missing two pieces I forgot to mention. You can create the project with dbt init and you must update the dbt_project.yml file to use the aspects profile. Sorry for going forward, once this is added I think is good to go

[pomegranited]

Nice gotcha, thanks @Ian2012 !
This is looking better: https://docsopenedxorg--111.org.readthedocs.build/projects/openedx-aspects/en/111/how-tos/dbt_extensions.html

[Ian2012]

LGTM, just a couple of nits

[bmtcril]

Two last little things then feel free to merge, thanks!

[bmtcril]

Suggested change

	Aspects charts depend on the transforms in `aspects-dbt`_, so it's important that your ``dbt`` package also installs
	Aspects charts depend on the transforms in `aspects-dbt`_, so it's important that your ``dbt`` package also installs the same version of `aspects-dbt`_ as your `tutor_contrib_aspects` plugin uses.

[pomegranited]

Good point -- I updated "step 2" to better illustrate what those package.yml values should be:

https://docsopenedxorg--111.org.readthedocs.build/projects/openedx-aspects/en/111/how-tos/dbt_extensions.html

[bmtcril]

Should note here that it will also need to contain all of the contents of the aspects-dbt packages.yml too, I believe.

[Ian2012]

Is it true? I don't think so. I've been using it with only the aspects-dbt for two other projects and it has shown no issues. I think dependencies are installed recursively

[pomegranited]

@bmtcril I think @Ian2012 is correct here.

I couldn't find docs that verify it, which I would expect to find if dbt dependencies didn't work like other package dependencies.

I also dug through the dbt packages on dbt hub to find an example. This demo project depends on dbt-codegen, which in turn depends on dbt-utils, but dbt-utils need not be present in the parent's packages.yml.

[openedx-webhooks]

@pomegranited 🎉 Your pull request was merged! Please take a moment to answer a two question survey so we can improve your experience in the future.