Merge branch 'main' into sending-quarto-emails

Author: juleswg23

.github/workflows/ci.yml

@@ -1,51 +1,51 @@
 name: Build and Deploy
 on: [push, pull_request]
 permissions:
-    contents: write
+  contents: write
 jobs:
-    build-and-deploy:
-        concurrency: ci-${{ github.ref }}
-        runs-on: ubuntu-latest
-        permissions:
-            pull-requests: write
-            actions: write
-            contents: write
-        steps:
-            - name: Checkout 🛎️
-              uses: actions/checkout@v4
+  build-and-deploy:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      actions: write
+      contents: write
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
 
-            # python ----
-            - uses: actions/checkout@v2
-            - name: Install uv
-              uses: astral-sh/setup-uv@v5
-            - name: "Set up Python"
-              uses: actions/setup-python@v5
-              with:
-                python-version-file: ".python-version"
+      # python ----
+      - uses: actions/checkout@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
 
-            - name: Install the project
-              run: uv sync --all-extras --dev
+      - name: Install the project
+        run: uv sync --all-extras --dev
 
-            # quarto docs build ----
-            - uses: quarto-dev/quarto-actions/setup@v2
-              with:
-                  tinytex: true
+      # quarto docs build ----
+      - uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          tinytex: true
 
-            - name: Build docs
-              run: |
-                  uv run quarto render
+      - name: Build docs
+        run: |
+          uv run quarto render
 
-            - name: Deploy
-              uses: JamesIves/github-pages-deploy-action@v4
-              if: ${{ github.ref == 'refs/heads/main' }}
-              with:
-                  force: false
-                  folder: _book
-                  clean-exclude: pr-preview
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          force: false
+          folder: _site
+          clean-exclude: pr-preview
 
-            - name: Deploy (preview)
-              uses: rossjrw/pr-preview-action@v1
-              # if in a PR
-              if: ${{ github.event_name == 'pull_request' }}
-              with:
-                  source-dir: _book
+      - name: Deploy (preview)
+        uses: rossjrw/pr-preview-action@v1
+        # if in a PR
+        if: ${{ github.event_name == 'pull_request' }}
+        with:
+          source-dir: _site

_quarto.yml

@@ -1,34 +1,38 @@
 project:
-  type: book
+  type: website
 
-book:
+website:
   title: "Email for Data Science"
-  author: "Norah Jones"
-  date: "10/6/2025"
-  chapters:
-    - index.qmd
-    - summary.qmd
-    - part: Content
-      chapters: 
-        - content-embedding.qmd
-        - content-layout.qmd
-    - part: Configuring
-      chapters:
-        - configuring-subject.qmd
-        - configuring-attachments.qmd
-    - part: Orchestrating
-      chapters: 
-        - orchestrating-auth.qmd
-        - orchestrating-tests.qmd
+  site-url: https://posit-dev.github.io/email-for-data-science/
+  navbar:
+    left:
+      - text: User Guide
+        file: index.qmd
+      - text: Reference
+        file: reference/index.qmd
+  sidebar:
+    - title: User Guide
+      contents:
+        - index.qmd
+        - summary.qmd
+        - section: Content
+          contents: 
+            - content-embedding.qmd
+            - content-layout.qmd
+        - section: Configuring
+          contents:
+            - configuring-subject.qmd
+            - configuring-attachments.qmd
+        - section: Orchestrating
+          contents:
+            - orchestrating-auth.qmd
+            - orchestrating-tests.qmd
 
 
 format:
   html:
     theme:
       - cosmo
       - brand
-  pdf:
-    documentclass: scrreprt
-
 
 

assets/whole-game-email-annotated.png

@@ -0,0 +1,22 @@
+---
+title: "Email report generation with Quarto"
+jupyter: python3
+format: email
+---
+
+:::{.email}
+
+:::{.subject}
+Report on cars
+:::
+
+
+```{python}
+# | code-fold: true
+# | eval: false
+from data_polars import sp500
+
+sp500.head(10).style
+```
+
+:::

assets/whole-game-email.png

@@ -0,0 +1,3 @@
+---
+title: This will be the reference index
+---

assets/whole-game-fancy.png

@@ -10,7 +10,119 @@
 * Orchestration: testing email 
 -->
 
+Emailing reports is a critical but challenging task for data science.
+Mainly because you have to figure out generating the email content, configuring pieces like attachments, and orchestrating it (e.g. testing, or sending on a schedule). Moreover, content can range from simple layouts to more complex ones.
 
+In this tutorial, we'll walk through the whole game of sending email. We'll start with this simple example:
+
+```{python}
+# | code-fold: true
+# | eval: false
+import os
+from dotenv import load_dotenv
+from data_polars import sp500
+import redmail
+
+load_dotenv()
+gmail_address = os.environ["GMAIL_ADDRESS"]
+gmail_app_password = os.environ["GMAIL_APP_PASSWORD"]
+
+
+email_subject = "Report on Cars"
+email_body = sp500.head(10).style.as_raw_html(inline_css=True)
+
+# This is here to emphasize the sender does not have to be the same as the receiver
+email_receiver = gmail_address
+
+redmail.gmail.username = gmail_address
+redmail.gmail.password = gmail_app_password
+
+redmail.gmail.send(
+    subject=email_subject,
+    receivers=[email_receiver],
+    html=email_body,
+)
+```
+
+
+![](./assets/whole-game-email-annotated.png){width=50% fig-align="center"}
+
+* **Content**: writing the text of the email, including plots and tables.
+* **Composing**: setting up the subject, sender, and receivers.
+* **Orchestrating**: previewing, testing, and scheduling the email.
+
+We'll also quickly review writing more advanced content layouts, and authoring email reports that involve running code with Quarto.
+
+## A simple email
+
+![](./assets/whole-game-email.png){width=50% fig-align="center"}
+
+* Generate and preview
+* Authenticate (may need to refer to its own authentication page in guide)
+* Send
+
+```{python}
+# | code-fold: true
+# | eval: false
+import os
+from dotenv import load_dotenv
+from data_polars import sp500
+import redmail
+
+load_dotenv()
+gmail_address = os.environ["GMAIL_ADDRESS"]
+gmail_app_password = os.environ["GMAIL_APP_PASSWORD"]
+
+
+email_subject = "Report on Cars"
+email_body = sp500.head(10).style.as_raw_html(inline_css=True)
+
+# This is here to emphasize the sender does not have to be the same as the receiver
+email_receiver = gmail_address
+
+redmail.gmail.username = gmail_address
+redmail.gmail.password = gmail_app_password
+
+redmail.gmail.send(
+    subject=email_subject,
+    receivers=[email_receiver],
+    html=email_body,
+)
+```
+
+## Configure: subject, recipients, attachments
+
+* you could attach the data as a CSV attachment
+
+
+## Orchestrate: save and preview
+
+* previewing email
+* intermediate json, easy for sending email later
+* embedding images makes previewing hard
+* can always email to yourself (or use a test service like Litmus)
+
+## Content: Quarto authoring
+
+Here's our same simple email generated using quarto.
+
+
+
+![](./assets/whole-game-quarto.png){width=50% fig-align="center"}
+
+* Focused on basic configuring, and content
+* Sending happens via our tool
+* Generate using quarto render
+* Can preview email
+
+## Content: advanced layouts
+
+We'll highlight the key pieces (discussed later in this guide) to go from that simple email, to a more advanced on like below:
+
+![](./assets/whole-game-fancy.png){width=50% fig-align="center"}
+
+
+## Fridge
 
 In this tutorial, we are going to send an email from a Gmail account. To do so, you will need to [create an App Password](https://support.google.com/accounts/answer/185833). Note this is only possible if you've [enabled 2-step verification](https://support.google.com/accounts/answer/185839).