Merge pull request #72 from cagov/dbt-docs

dbt docs

.github/workflows/docs.yml

@@ -13,9 +13,28 @@ jobs:
       - uses: actions/setup-python@v4
         with:
           python-version: 3.x
+      - id: auth
+        name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v1
+        with:
+          # The credentials here can read metadata, data, and create jobs (execute
+          # queries), which allows it to compile the dbt project and generate docs.
+          credentials_json: ${{ secrets.GOOGLE_CREDENTIALS }}
+          export_environment_variables: true
       - uses: actions/cache@v2
         with:
           key: ${{ github.ref }}
           path: .cache
-      - run: pip install mkdocs-material
-      - run: mkdocs gh-deploy --force
+      - name: Install dependencies
+        run: |
+          pip install -r transform/requirements.txt
+          pip install mkdocs-material
+      - name: Build dbt docs
+        env:
+          DBT_PROFILES_DIR: transform/ci
+        run: |
+          dbt deps --project-dir=transform
+          dbt docs generate --project-dir=transform
+          cp -r transform/target docs/dbt_docs
+      - name: Deploy 🚀
+        run: mkdocs gh-deploy --force

.gitignore

@@ -1,4 +1,5 @@
 *.swp
+docs/dbt_docs
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

.pre-commit-config.yaml

@@ -76,7 +76,7 @@ repos:
         id: dbt-deps
         language: python
         entry: dbt deps --project-dir=transform
-        always_run: true
+        always_run: false
         pass_filenames: false
         types: [sql]
         additional_dependencies:

mkdocs.yml

@@ -31,6 +31,7 @@ nav:
   - Security Guidelines: security.md
   - Cloud Infrastructure: cloud-infrastructure.md
   - Writing Documentation: writing-documentation.md
+  - dbt Project: /dbt_docs/index.html
   - Learning:
       - git: learning/git.md
       - dbt: learning/dbt.md

transform/models/overview.md

@@ -0,0 +1,37 @@
+{% docs __overview__ %}
+
+# CalData dbt Documentation
+
+Welcome to the CalData Data Services and Engineering `dbt` docs.
+To go back to the top-level docs, follow [this link](../)
+
+## Navigation
+
+You can use the `Project` and `Database` navigation tabs on the left side of the window to explore the models in your project.
+
+### Project Tab
+
+The Project tab mirrors the directory structure of your dbt project.
+In this tab, you can see all of the models defined in your dbt project, as well as models imported from dbt packages.
+
+### Database Tab
+
+The Database tab also exposes your models, but in a format that looks more like a database explorer.
+This view shows relations (tables and views) grouped into database schemas.
+Note that ephemeral models are not shown in this interface, as they do not exist in the database.
+
+## Graph Exploration
+
+You can click the blue icon on the bottom-right corner of the page to view the lineage graph of your models.
+
+On model pages, you'll see the immediate parents and children of the model you're exploring.
+By clicking the Expand button at the top-right of this lineage pane,
+you'll be able to see all of the models that are used to build, or are built from,
+the model you're exploring.
+
+Once expanded, you'll be able to use the `--select` and `--exclude` model selection syntax to filter the models in the graph.
+For more information on model selection, check out the [dbt docs](https://docs.getdbt.com/reference/node-selection/syntax).
+
+Note that you can also right-click on models to interactively filter and explore the graph.
+
+{% enddocs %}