Merge pull request #1 from rfdearborn/rfdearborn/initialize

Initialize!

Author: rfdearborn

README.md

@@ -1,2 +1,52 @@
 # dbt-docs-to-notion
-A github action for exporting dbt docs to a notion database
+A Github action for exporting dbt model docs to a Notion database, where they can be conveniently consumed (especially by casual users in your org).
+
+## Output
+A Notion database, within a page of your choosing, with records like this:
+![dbt docs to notion output](https://i.imgur.com/Y1EWj9l.png)
+
+## Usage
+### Prerequisites
+In advance of using this action, you should:
+1. [Create a new integration within your Notion workspace](https://www.notion.so/my-integrations)
+2. Have your Notion integration token and a working dbt `profiles.yml` accessible to your repo (I'd recommend using [Github's repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets); see example workflow below).
+### Inputs
+- `dbt-package`: dbt-bigquery, dbt-postgres, dbt-bigquery==1.0.0, etc. (**required**)
+- `dbt-profile-path`: where profile.yml lives (default: `./`)
+- `dbt-target`: profile target to use for dbt docs generation (**required**)
+- `model-records-to-write`: "all" or "model_name_1 model_name_2 ..." (default: "all")
+- `notion-database-name`: what to name the Notion database of dbt models (**required**)
+- `notion-parent-id`: Notion page where database of dbt models will be added (**required**)
+- `notion-token`: Notion token API for integration to use (pass using secrets) (**required**)
+
+### Post-initialization Touchups
+Unfortunately, Notion's API doesn't allow for setting the order of properties or records in a database. Thus, after creating your database, you'll probably want to do some re-arranging (I'd recommend adding a table view to your database's parent page).
+
+### Example workflow
+```
+name: dbt Docs to Notion
+
+on:
+  - pull_request
+
+jobs:
+  dbt-docs-to-notion:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Create temp dbt profiles
+        run: "printf %s \"$DBT_PROFILES\" > ./profiles.yml"
+        env:
+          DBT_PROFILES: ${{ secrets.DBT_PROFILES }}
+      - name: dbt-docs-to-notion
+        uses: ./.github/actions/dbt-docs-to-notion
+        with:
+          dbt-package: 'dbt-bigquery==1.0.0'
+          dbt-profile-path: './'
+          dbt-target: 'github_actions'
+          model-records-to-write: "all"
+          notion-database-name: 'dbt Models'
+          notion-parent-id: 'your-page-id-here'
+          notion-token: '${{ secrets.DBT_DOCS_TO_NOTION_TOKEN }}'
+```

action.yml

@@ -0,0 +1,52 @@
+name: 'dbt-docs-to-notion'
+description: 'Exports dbt model docs to a Notion database'
+branding:
+  icon: 'book-open'
+  color: 'orange'
+inputs:
+  dbt-package:
+    description: 'dbt-bigquery, dbt-postgres, dbt-bigquery==1.0.0, etc.'
+    required: true
+  dbt-profile-path:
+    description: 'where profile.yml lives'
+    required: false
+    default: './'
+  dbt-target:
+    description: 'profile target to use for dbt docs generation'
+    required: true
+  model-records-to-write:
+    description: \"all\" or \"model_name_1 model_name_2 ...\"
+    required: false
+    default: "all"
+  notion-database-name:
+    description: 'what to name the Notion database of dbt models'
+    required: true
+  notion-parent-id:
+    description: 'Notion page where database of dbt models will be added'
+    required: true
+  notion-token:
+    description: 'Notion token api for integration to use (pass using secrets)'
+    required: true
+runs:
+  using: 'composite'
+  steps: 
+    - name: Install Python
+      uses: "actions/setup-python@v2"
+      with:
+          python-version: "3.7"
+    - name: Install dbt
+      run: "pip3 install ${{ inputs.dbt-package }}"
+      shell: bash
+    - name: Load dbt deps
+      run: "dbt deps --profiles-dir ${{ inputs.dbt-profile-path }} --target=${{ inputs.dbt-target }}"
+      shell: "bash"
+    - name: Generate dbt Docs
+      run: "dbt docs generate --profiles-dir ${{ inputs.dbt-profile-path }} --target=${{ inputs.dbt-target }}"
+      shell: bash
+    - name: Export dbt Docs to Notion
+      run: "python3 ./.github/actions/dbt-docs-to-notion/dbt_docs_to_notion.py ${{ inputs.model-records-to-write }}"
+      shell: bash
+      env:
+        DATABASE_NAME: ${{ inputs.notion-database-name }}
+        DATABASE_PARENT_ID: ${{ inputs.notion-parent-id }}
+        NOTION_TOKEN: ${{ inputs.notion-token }}