docs and repr upgrades

Author: juleswg23

docs/_quarto.yml

@@ -77,6 +77,22 @@ quartodoc:
       contents:
         - write_email_message_to_file
 
+    - title: Templated Authoring
+      desc: >
+        Write responsive emails with the Blastula template
+      package: nbmail
+      contents:
+        - compose.compose_email
+        - compose.create_blocks
+        - compose.block_text
+        - compose.block_title
+        - compose.block_spacer
+        - compose.block_image
+        - compose.block_plot
+        - compose.md
+        - compose.add_cta_button
+        - compose.add_readable_time
+
     - title: MJML Authoring
       desc: >
         Write responsive emails with MJML

nbmail/compose/blocks.py

@@ -5,6 +5,7 @@
 from .inline_utils import _is_url, _process_markdown
 
 
+
 __all__ = [
     "Block",
     "BlockList",
@@ -48,6 +49,22 @@ def _to_mjml(self) -> MJMLTag:
         """
         return self._mjml_tag
 
+    def _repr_html_(self) -> str:
+        """
+        Return HTML representation for rich display in Jupyter notebooks.
+
+        Examples
+        --------
+        ```{python}
+        from nbmail.compose import block_text
+
+        block = block_text("Hello world!")
+        block 
+        ```
+        """
+        block_list = BlockList(self)
+        return block_list._repr_html_()
+
 
 class BlockList:
     """
@@ -62,7 +79,7 @@ class BlockList:
     --------
     Users typically create BlockList via the `create_blocks()` function:
 
-    ```python
+    ```{python}
     from nbmail.compose import create_blocks, block_text, block_title
 
     content = create_blocks(
@@ -80,6 +97,36 @@ def __init__(self, *args: Union["Block", str]):
             One or more `Block` objects or strings.
         """
         self.sections = list(args)
+    
+    def _repr_html_(self) -> str:
+        """
+        Return HTML representation for rich display in Jupyter notebooks.
+
+        This method wraps the BlockList in a compose_email() call and delegates
+        to the Email's _repr_html_() method for rendering, enabling interactive
+        preview of blocks directly in notebooks.
+
+        Returns
+        -------
+        str
+            HTML content with inline attachments embedded as base64 data URIs.
+
+        Examples
+        --------
+        ```{python}
+        from nbmail.compose import create_blocks, block_title, block_text
+
+        content = create_blocks(
+            block_title("My Email"),
+            block_text("Hello world!")
+        )
+        content
+        ```
+        """
+        from .compose import compose_email
+
+        email = compose_email(body=self)
+        return email._repr_html_()
 
     def _to_mjml_list(self) -> list[MJMLTag]:
         """
@@ -134,12 +181,14 @@ def block_text(
 
     Examples
     --------
-    ```python
+    ```{python}
     from nbmail.compose import block_text
 
     # Simple text
     block = block_text("Hello world")
 
+    print(1+1)
+
     # Markdown text
     block = block_text("This is **bold** and this is *italic*")
 
@@ -179,14 +228,10 @@ def block_title(
 
     Examples
     --------
-    ```python
+    ```{python}
     from nbmail.compose import block_title
 
-    # Simple title
-    title = block_title("My Newsletter")
-
-    # Centered title (default)
-    title = block_title("Welcome!", align="center")
+    block_title("My Newsletter")
     ```
     """
 
@@ -226,10 +271,10 @@ def block_spacer(height: str = "20px") -> Block:
 
     Examples
     --------
-    ```python
+    ```{python}
     from nbmail.compose import block_spacer, create_blocks, block_text
 
-    email_body = create_blocks(
+    create_blocks(
         block_text("First section"),
         block_spacer("30px"),
         block_text("Second section"),
@@ -292,14 +337,14 @@ def block_image(
 
     Examples
     --------
-    ```python
-    from nbmail.compose import block_image, create_blocks, block_text
+    ```{python}
+    from nbmail.compose import block_image, create_blocks, block_text, compose_email, md
 
-    email = compose_email(
+    compose_email(
+        title="Product Feature",
         body=create_blocks(
-            block_text("Here's an image:"),
-            block_image("path/to/image.png", alt="Example", width=600),
-            block_text("And some text after it.")
+            block_text(md("Check this out:")),
+            block_image("https://fastly.picsum.photos/id/630/300/200.jpg?hmac=dSM5_yM5Z9Pb3CX6OviVW3dEbyHmkD04otrIKU2LQ50", alt="Product image", width="500px")
         )
     )
     ```
@@ -409,16 +454,17 @@ def block_plot(
 
     Examples
     --------
-    ```python
-    from nbmail.compose import block_plot, create_blocks, block_text
-    from plotnine import ggplot, aes, geom_point, mtcars
+    ```{python}
+    from nbmail.compose import block_plot, create_blocks, block_text, compose_email
+    from plotnine import ggplot, aes, geom_point
+    from great_tables.data import gtcars
 
     plot = (
-        ggplot(mtcars, aes("disp", "hp"))
+        ggplot(gtcars, aes("trq", "hp"))
         + geom_point()
     )
 
-    email = compose_email(
+    compose_email(
         body=create_blocks(
             block_text("Here's my plot:"),
             block_plot(plot, alt="Scatter plot"),

nbmail/compose/compose.py

@@ -38,10 +38,10 @@ def create_blocks(*args: Union[Block, str]) -> BlockList:
 
     Examples
     --------
-    ```python
+    ```{python}
     from nbmail.compose import create_blocks, block_text, block_title, block_spacer
 
-    content = create_blocks(
+    create_blocks(
         block_title("Welcome!"),
         block_text("This is the main content."),
         block_spacer("20px"),
@@ -100,21 +100,21 @@ def compose_email(
     --------
     Simple email with single block:
 
-    ```python
+    ```{python}
     from nbmail.compose import compose_email, block_text
 
-    email = compose_email(
+    compose_email(
         body=block_text("This is a simple email.")
     )
     ```
 
     Email with title/header and multiple blocks:
 
-    ```python
+    ```{python}
     from nbmail.compose import compose_email, create_blocks, block_title, block_text
 
-    email = compose_email(
-        title="Welcome!",  # Creates a large title block at top
+    compose_email(
+        title="Welcome!",
         body=create_blocks(
             block_text("Welcome to this week's update!"),
             block_text("Here's what's new...")
@@ -124,10 +124,10 @@ def compose_email(
 
     Email with header section and body:
 
-    ```python
+    ```{python}
     from nbmail.compose import compose_email, create_blocks, block_title, block_text
 
-    email = compose_email(
+    compose_email(
         header=create_blocks(block_title("Newsletter")),
         body=create_blocks(
             block_text("Welcome to this week's update!"),
@@ -136,21 +136,6 @@ def compose_email(
         footer=create_blocks(block_text("© 2025 My Company"))
     )
     ```
-
-    Email with embedded images:
-
-    ```python
-    from nbmail.compose import compose_email, block_image, block_text, md, create_blocks
-
-    # Use block_image for embedding local files or URLs
-    email = compose_email(
-        title="Product Feature",
-        body=create_blocks(
-            block_text(md("Check this out:")),
-            block_image("path/to/image.png", alt="Product image", width="500px")
-        )
-    )
-    ```
     """
     # Convert sections (header, body, footer) to MJML lists
     header_mjml_list = _component_to_mjml_section(header)

nbmail/compose/inline_utils.py

@@ -62,14 +62,13 @@ def md(text: str) -> str:
 
     Examples
     --------
-    ```python
-    from nbmail.compose import md, block_text
+    ```{python}
+    from nbmail.compose import md, block_text, compose_email
 
-    # Simple markdown
     html = md("This is **bold** and this is *italic*")
 
     # Use in a block
-    email = compose_email(body=block_text(html))
+    compose_email(body=block_text(html))
     ```
     """
     return _process_markdown(text)
@@ -184,12 +183,12 @@ def add_cta_button(
 
     Examples
     --------
-    ```python
+    ```{python}
     from nbmail.compose import add_cta_button, block_text, compose_email
 
     button_html = add_cta_button("Learn More", "https://example.com")
 
-    email = compose_email(
+    compose_email(
         body=block_text(f"Ready?\\n\\n{button_html}")
     )
     ```
@@ -234,18 +233,13 @@ def add_readable_time(
 
     Examples
     --------
-    ```python
+    ```{python}
     from datetime import datetime
     from nbmail.compose import add_readable_time, block_text, compose_email
 
     time_str = add_readable_time(datetime.now())
-    # Output: "November 10, 2025"
 
-    # Custom format
-    time_str = add_readable_time(datetime.now(), format_str="%A, %B %d")
-    # Output: "Sunday, November 10"
-
-    email = compose_email(
+    compose_email(
         body=block_text(f"Report generated: {time_str}")
     )
     ```

nbmail/egress.py

@@ -325,26 +325,6 @@ def send_email_with_smtp(
         email,
         security="tls"
     )
-
-    # SSL connection (port 465)
-    send_email_with_smtp(
-        "smtp.example.com",
-        465,
-        "user@example.com",
-        "password123",
-        email,
-        security="ssl"
-    )
-
-    # Plain SMTP (port 25) - insecure, for testing only
-    send_email_with_smtp(
-        "127.0.0.1",
-        8025,
-        "test@example.com",
-        "password",
-        email,
-        security="smtp"
-    )
     ```
     """
     if security not in ("tls", "ssl", "smtp"):