Merge pull request #11 from posit-dev/refactor-docs

feat: add mjml authoring support.

Author: juleswg23

.github/workflows/ci.yml

@@ -31,31 +31,31 @@ jobs:
         run: uv sync --all-extras --dev
 
       - name: Install emailer-lib
-        run: uv pip install -e "./emailer-lib"
+        run: uv pip install -e .
 
       # quarto docs build ----
       - uses: quarto-dev/quarto-actions/setup@v2
-        with:
-          tinytex: true
+        # with:
+        #   tinytex: true
 
       - name: Build docs
         run: |
-          uv run quartodoc build --verbose && uv run quarto render
+          cd docs && uv run quartodoc build --verbose && uv run quarto render
 
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4
         if: ${{ github.ref == 'refs/heads/main' }}
         with:
           force: false
-          folder: _site
+          folder: docs/_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: _site
+          source-dir: docs/_site
 
   test-emailer-lib:
     runs-on: ubuntu-latest
@@ -81,18 +81,18 @@ jobs:
         run: uv sync --all-extras --dev
 
       - name: Install emailer-lib
-        run: uv pip install -e "./emailer-lib"
+        run: uv pip install -e .
 
       - name: Install the project deps
-        run: uv pip install -e "./emailer-lib[dev]"
+        run: uv pip install -e .[dev]
 
       - name: Test emailer-lib
         run: |
-          uv run pytest emailer-lib/emailer_lib/tests/ --cov=emailer_lib --cov-report=xml --cov-report=term-missing
+          uv run pytest emailer_lib/tests/ --cov=emailer_lib --cov-report=xml --cov-report=term-missing
       
       - name: Upload coverage reports
         uses: codecov/codecov-action@v4
         if: ${{ matrix.python-version == '3.12' }}
         with:
           file: emailer-lib/coverage.xml
-          flags: emailer-lib
+          flags: emailer-lib

.gitignore

@@ -212,4 +212,4 @@ _site
 
 .DS_Store
 
-.vscode
+.vscode

Makefile

@@ -0,0 +1,14 @@
+build-docs: generate-mjml-tags
+	cd docs && uv run quartodoc build --verbose && quarto render
+
+preview:
+	cd docs && quarto preview
+
+test:
+	pytest emailer_lib/tests emailer_lib/mjml/tests --cov-report=xml
+
+test-update:
+	pytest emailer_lib/tests emailer_lib/mjml/tests --snapshot-update
+
+generate-mjml-tags:
+	python3 emailer_lib/mjml/scripts/generate_tags.py

README.md

@@ -1 +1,84 @@
-# email-for-data-science
+# emailer-lib
+
+<!-- [![Python Versions](https://img.shields.io/pypi/pyversions/gt_extras.svg)](https://pypi.python.org/pypi/gt-extras) -->
+<!-- [![PyPI](https://img.shields.io/pypi/v/gt-extras?logo=python&logoColor=white&color=orange)](https://pypi.org/project/gt-extras/) -->
+<!-- [![PyPI Downloads](https://static.pepy.tech/badge/gt-extras)](https://pepy.tech/projects/gt-extras) -->
+<!-- [![License](https://img.shields.io/github/license/posit-dev/email-for-data-science)](https://github.com/posit-dev/email-for-data-science/blob/main/LICENSE) -->
+
+<!-- [![Tests](https://github.com/posit-dev/gt-extras/actions/workflows/ci_tests.yml/badge.svg)](https://github.com/posit-dev/gt-extras/actions/workflows/ci_tests.yml) -->
+[![Documentation](https://img.shields.io/badge/docs-project_website-blue.svg)](https://posit-dev.github.io/email-for-data-science/reference/)
+<!-- [![Repo Status](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) -->
+<!-- [![Contributors](https://img.shields.io/github/contributors/posit-dev/gt-extras)](https://github.com/posit-dev/gt-extras/graphs/contributors) -->
+<!-- [![Codecov](https://codecov.io/gh/posit-dev/gt-extras/branch/main/graph/badge.svg)](https://codecov.io/gh/posit-dev/gt-extras) -->
+
+> ⚠️ **emailer-lib is currently in development, expect breaking changes.**
+
+
+### What is [emailer-lib](https://posit-dev.github.io/email-for-data-science/reference/)?
+
+**emailer-lib** is a Python package for serializing, previewing, and sending email messages in a consistent, simple structure. It provides utilities to convert emails from different sources (Redmail, Yagmail, MJML, Quarto JSON) into a unified intermediate format, and send them via multiple backends (Gmail, SMTP, Mailgun, etc.).
+
+The package is designed for data science workflows and Quarto projects, making it easy to generate, preview, and deliver rich email content programmatically.
+
+<!-- ## Installation
+Install the latest release from your local repo or PyPI:
+
+```bash
+pip install -e ./emailer-lib
+```
+-->
+
+## Example Usage
+
+```python
+from emailer_lib import (
+    quarto_json_to_intermediate_email,
+    IntermediateEmail,
+    send_intermediate_email_with_gmail,
+)
+
+# Read a Quarto email JSON file
+email_struct = quarto_json_to_intermediate_email("email.json")
+
+# Preview the email as HTML
+email_struct.write_preview_email("preview.html")
+
+# Send the email via Gmail
+send_intermediate_email_with_gmail("[email protected]", "your_password", email_struct)
+```
+
+## Features
+
+- **Unified email structure** for serialization and conversion
+- **Convert** emails from Redmail, Yagmail, MJML, and Quarto JSON
+- **Send** emails via Gmail, SMTP, Mailgun, and more
+- **Preview** emails as HTML files
+- **Support for attachments** (inline and external)
+- **Simple API** for integration in data science and reporting workflows
+
+## Contributing
+If you encounter a bug, have usage questions, or want to share ideas to make this package better, please feel free to file an [issue](https://github.com/posit-dev/email-for-data-science/issues).
+
+<!-- 
+## Code of Conduct
+Please note that the **gt-extras** project is released with a [contributor code of conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).<br>By participating in this project you agree to abide by its terms. -->
+
+<!-- ## 📄 License
+
+**Great Tables** is licensed under the MIT license.
+
+© Posit Software, PBC. -->
+
+<!-- ## Citation
+If you use **gt-extras** in your work, please cite the package:
+
+```bibtex
+@software{gt_extras,
+authors = {Jules Walzer-Goldfeld, Michael Chow, and Rich Iannone},
+license = {MIT},
+title = {{gt-extras: Extra helpers for great-tables in Python.}},
+url = {https://github.com/posit-dev/gt-extras}, version = {0.0.1}
+}
+``` -->
+
+For more information, see the [docs](https://posit-dev.github.io/email-for-data-science/reference) or [open an issue](https://github.com/posit-dev/email-for-data-science/issues) with questions or suggestions!

cover.png

@@ -0,0 +1,2 @@
+/.quarto/
+/reference/

docs/.gitignore

@@ -70,13 +70,52 @@ quartodoc:
         - send_intermediate_email_with_mailgun
         - send_quarto_email_with_gmail
 
-
     - title: Utilities
       desc: >
         Previews and more 
       contents:
         - write_email_message_to_file
 
+    - title: MJML Authoring
+      desc: >
+        Write responsive emails with MJML
+      package: emailer_lib
+      contents:
+        - mjml.mjml
+        - mjml.head
+        - mjml.body
+        - mjml.mj_attributes
+        - mjml.mj_all
+        - mjml.mj_class
+        - mjml.breakpoint
+        - mjml.font
+        - mjml.html_attributes
+        - mjml.html_attribute
+        - mjml.preview
+        - mjml.style
+        - mjml.title
+        - mjml.accordion
+        - mjml.accordion_element
+        - mjml.accordion_text
+        - mjml.accordion_title
+        - mjml.button
+        - mjml.carousel
+        - mjml.carousel_image
+        - mjml.column
+        - mjml.divider
+        - mjml.group
+        - mjml.hero
+        - mjml.image
+        - mjml.navbar
+        - mjml.navbar_link
+        - mjml.raw
+        - mjml.section
+        - mjml.social
+        - mjml.social_element
+        - mjml.spacer
+        - mjml.table
+        - mjml.text
+        - mjml.wrapper
 
 format:
   html: