Tweaks to dbt and xAPI extending docs (#229)

* docs: add link to dbt debugging guide
* docs: fix links and example code
* docs: models can be configured in several ways, so link to these docs

docs/technical_documentation/how-tos/dbt_extensions.rst

@@ -119,8 +119,8 @@ Our new model calculates the average number of attempts made by users on each pr
       )
   group by problem_id
 
-Next, make sure your model is configured in the ``db_project.yml``. If you forget this step, dbt will warn you when
-running your package.
+Next, make sure your model is configured, for example in the ``db_project.yml``. If you forget this step, dbt will warn
+you when running your package.
 
 .. code-block:: yaml
 
@@ -130,7 +130,7 @@ running your package.
       +materialized: view
 
 
-See `About dbt models`_ to learn more.
+See `Configure dbt models`_ to learn more.
 
 Step 5. Add tests
 =================
@@ -207,7 +207,7 @@ You may need to repeat steps 4-6 a few times to resolve any warnings or errors t
 Don't forget to push your changes to your repo before running the tutor dbt command: it fetches a clean copy of your
 configured package repo + branch each time it runs.
 
-See `dbt debugging`_ for more information on how to debug issues with your package.
+See `dbt debugging`_ and `The missing guide to debug() in dbt`_ for more information on how to debug issues with your package.
 
 
 References
@@ -219,6 +219,7 @@ References
 * `Writing data tests`_: dbt's guide to writing package tests
 * `dbt commands`_: list of all dbt commands
 * `dbt debugging`_: guide for debugging issues with dbt
+* `The missing guide to debug() in dbt`_: detailed advice for debugging issues with dbt
 * `aspects-dbt`_: Aspects' dbt package
 * `aspects-dbt-example`_: the demo custom dbt package used in this tutorial.
 * `eduNEXT/dbt-aspects-unidigital`_: a real custom dbt package running in production Aspects
@@ -229,6 +230,7 @@ References
 .. _aspects-dbt requirements.txt: https://github.com/openedx/aspects-dbt/blob/main/requirements.txt
 .. _About dbt init: https://docs.getdbt.com/reference/commands/init
 .. _About dbt models: https://docs.getdbt.com/docs/build/models
+.. _Configure dbt models: https://docs.getdbt.com/reference/model-configs
 .. _Best practice guides: https://docs.getdbt.com/best-practices
 .. _dbt commands: https://docs.getdbt.com/reference/dbt-commands
 .. _dbt debugging: https://docs.getdbt.com/guides/debug-errors
@@ -238,3 +240,4 @@ References
 .. _Install dbt: https://docs.getdbt.com/docs/core/installation-overview
 .. _Writing data tests: https://docs.getdbt.com/best-practices/writing-custom-generic-tests
 .. _tutor-contrib-aspects plugin.py: https://github.com/openedx/tutor-contrib-aspects/blob/main/tutoraspects/plugin.py
+.. _The missing guide to debug() in dbt: https://docs.getdbt.com/blog/guide-to-jinja-debug

docs/technical_documentation/how-tos/xapi_transforms.rst

@@ -18,7 +18,7 @@ Transforming a new event
 Events emitted by ``openedx`` packages are transformed by `event-routing-backends`_ (ERB), a Django plugin which Aspects installs on Open edX.
 
 Transformers for events emitted by non-openedx packages should be stored close to the code that produces the events, and registered using decorators provided by `event-routing-backends`_. We
-will use OpenCraft's `completion aggregator`_ as the example for this tutorial, building on events emitted by `pr#173`_.
+will use OpenCraft's `completion aggregator`_ as the example for this tutorial, specifically code added `pr#205`_.
 
 xAPI Schema
 ===========
@@ -135,14 +135,14 @@ Result
 Some Open edX events use a "result" stanza that communicates information about the effect that this event had. For example, "problem check" events record whether the problem was answered
 correctly, and what score the actor received.
 
-For these completion "progressed" events, we would want to store:
+For these completion "progressed" events, we would want to store the percent completed, so we use an extension:
 
 .. code-block:: json
 
   {
     "completion": false,
-    "score": {
-      "scaled": ".45"
+    "extensions": {
+      "https://w3id.org/xapi/cmi5/result/extensions/progress": "45"
     }
   }
 
@@ -151,7 +151,7 @@ Implementation
 ==============
 
 Once the xAPI event schema is settled, the implementation should be pretty straightforward using
-`event-routing-backends`_ and `TinCan`_.
+`event-routing-backends`_ and `TinCan`_. See `pr#205`_ for full example code.
 
 #. Create a new transformer class that extends `XApiTransformer`_.
 #. Implement the ``get_verb`` method, returning your chosen verb URI and its short name.
@@ -160,10 +160,13 @@ Once the xAPI event schema is settled, the implementation should be pretty strai
    For example, to customize the context activities for your event, override ``get_context_activities``.
 
    Use the built-in transformer method ``get_data`` to parse and return data from the original tracking event.
-#. Register your transformer class using the registry decorator.
+#. Register your transformer class using the ``XApiTransformersRegistry.registry`` decorator.
 
    Use the raw tracking event's ``type`` as the parameter to ensure this class is used to transform those type of events.
 
+#. Write data transform tests by subclassing `XApiTransformersFixturesTestMixin` and adding ``raw`` JSON and ``expected``
+   xAPI event fixture data.
+
 
 .. warning::
    There can only be one registered xAPI transformer class per tracking event ``type``.
@@ -223,13 +226,13 @@ Here is the full code for the new transformer described in this tutorial.
 
   # Register subclasses for each individual event type
 
-  @XApiTransformersRegistry.register("edx.completion_aggregator.progress.chapter")
-  @XApiTransformersRegistry.register("edx.completion_aggregator.progress.sequential")
-  @XApiTransformersRegistry.register("edx.completion_aggregator.progress.vertical")
+  @XApiTransformersRegistry.register("openedx.completion_aggregator.progress.chapter")
+  @XApiTransformersRegistry.register("openedx.completion_aggregator.progress.sequential")
+  @XApiTransformersRegistry.register("openedx.completion_aggregator.progress.vertical")
   class ModuleProgressTransformer
       object_type = "http://adlnet.gov/expapi/activities/module"
 
-  @XApiTransformersRegistry.register("edx.completion_aggregator.progress.course")
+  @XApiTransformersRegistry.register("openedx.completion_aggregator.progress.course")
   class CourseProgressTransformer
       object_type = "http://adlnet.gov/expapi/activities/course"
 
@@ -309,7 +312,7 @@ References
 .. _ERB's xAPI filters: https://event-routing-backends.readthedocs.io/en/latest/getting_started.html#openedx-filters
 .. _external ID: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/external_user_ids/docs/decisions/0001-externalid.rst
 .. _openedx-filters: https://github.com/openedx/openedx-filters
-.. _pr#173: https://github.com/open-craft/openedx-completion-aggregator/pull/173
+.. _pr#205: https://github.com/open-craft/openedx-completion-aggregator/pull/205
 .. _progressed: http://adlnet.gov/expapi/verbs/progressed
 .. _TinCan: https://github.com/RusticiSoftware/TinCanPython
 .. _xAPI profiles: https://profiles.adlnet.gov/