Feat: Add macro signatures, expand README (#1)

* feat: Add macro signatures, expand README

* Fix: CI python setup

* Fix: dbt deps in CI

.github/workflows/ci.yml

@@ -16,9 +16,9 @@ jobs:
         uses: actions/checkout@v2
 
       - name: Install Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.9.6
+          python-version: '3.10'
 
       - name: Install dbt
         run: pip install -r requirements.txt

README.md

@@ -1,19 +1,38 @@
-# dbt Activity Schema <!-- omit in toc -->
+# dbt-activity-schema <!-- omit in toc -->
+
+A [dbt-Core](https://docs.getdbt.com/docs/introduction) [package](https://docs.getdbt.com/docs/build/packages#what-is-a-package) which contains macros to self-join an _activity stream_: the primary table in the [Activity Schema](https://github.com/ActivitySchema/ActivitySchema/blob/main/2.0.md) data modelling framework.
 
 ## Table of Contents <!-- omit in toc -->
 - [Install](#install)
 - [Usage](#usage)
+- [Contributions](#contributions)
 
 ## Install
 Include in `packages.yml`:
 
 ```yaml
 packages:
-  - git: "https://github.com/tnightengale/dbt_activity_schema.git"
+  - git: "https://github.com/tnightengale/dbt-activity-schema"
     revision: 0.0.1
 ```
 For latest release, see
 https://github.com/tnightengale/dbt-activity-schema/releases.
 
 ## Usage
-TODO
+Use the `dataset.sql` macro with the appropriate params to generate a self-joined dataset from the activity stream model in your project, eg:
+```SQL
+{{
+    dbt_activity_schema.dataset(
+        ref("example__activity_stream"),
+        dbt_activity_schema.primary_activity("All","bought something"),
+        [
+            dbt_activity_schema.append_activity("first_before", "visited page")
+        ]
+    )
+}}
+
+```
+See the signature in the macro for more details on each parameter.
+
+## Contributions
+Contributions and feedback are welcome. Please create an issue if you'd like to contribute.

integration_tests/scripts/ci.sh

@@ -1,3 +1,4 @@
 #!/bin/sh
 
+dbt deps
 dbt build -x

macros/dataclasses/append_activity.sql

@@ -4,29 +4,24 @@
 
 {% macro default__append_activity(relationship_name, activity_name) %}
 
-{# params
-
-relationship_name: str (enum)
-    The string identifier of the defined activity relationship, one of;
-        1. "first_ever"
-        2. "last_ever"
-        3. "first_before"
-        4. "last_before"
-        5. "first_after"
-        6. "last_after"
-        7. "aggregate_after"
-        8. "aggregate_all_ever"
-
-activity_name: str
-    The string identifier of the activity in the stream to append (join).
+{# An activity to append to the `primary_activity`.
+
+params:
+
+    relationship_name: str (enum)
+        The string identifier of the defined activity relationship, one of;
+            1. "first_ever"
+            2. "last_ever"
+            3. "first_before"
+            4. "last_before"
+            5. "first_after"
+            6. "last_after"
+            7. "aggregate_after"
+            8. "aggregate_all_ever"
+
+    activity_name: str
+        The string identifier of the activity in the stream to append (join).
 #}
-{# last_ever = last_ever()
-first_before = first_before()
-last_before = last_before()
-first_after = first_after()
-last_after = last_after()
-aggregate_after = aggregate_after()
-aggregate_all_ever = aggregate_all_ever() #}
 
 {% set relationship_factory = dict(
     first_before = dbt_activity_schema.first_before(),

macros/dataset.sql

@@ -14,6 +14,22 @@
     appended_activities
 ) %}
 
+{# Create a derived dataset using self-joins from an activity stream model.
+
+params:
+
+    activity_stream_ref: ref()
+        The dbt ref() that points to the activty stream table. Use the project
+        variables in ./dataclasses/columns.sql to set the columns of the activity
+        stream.
+
+    primary_activity: primary_activity (dataclass)
+        The primary activity of the derived dataset.
+
+    appended_activities: List[append_activity (dataclass)]
+        The list of appended activities to self-join to the primary activity.
+#}
+
 {% set columns = dbt_activity_schema.columns() %}
 {% set stream = dbt_activity_schema.globals().stream %}
 {% set alias = dbt_activity_schema.alias %}