Merge pull request #255 from adamtheturtle/admonition-support

Add support for `.. admonition`

Author: adamtheturtle

sample/index.rst

@@ -103,6 +103,17 @@ This text has :strike:`strike` formatting and :del:`deleted text` as well.
 
    This is an important admonition that highlights important information.
 
+.. admonition:: Custom Admonition Title
+
+   This is a generic admonition with a custom title. You can use this for
+   any type of callout that doesn't fit the standard admonition types.
+
+   It supports all the same features:
+
+   * Bullet points
+   * **Bold text** and *italic text*
+   * ``Code snippets``
+
 .. collapse:: Click to expand this section
 
    This content is hidden by default and can be expanded by clicking the toggle.

sample/spelling_wordlist.txt

@@ -1 +1,2 @@
 reStructuredText
+callout

src/sphinx_notion/__init__.py

@@ -867,6 +867,46 @@ def _(
     )
 
 
+@beartype
+@_process_node_to_blocks.register
+def _(
+    node: nodes.admonition,
+    *,
+    section_level: int,
+) -> list[Block]:
+    """Process generic admonition nodes by creating Notion Callout blocks.
+
+    Generic admonitions have a title as the first child, followed by
+    content. The title becomes the callout text, and all content becomes
+    nested blocks.
+    """
+    del section_level
+
+    # Extract the title from the first child (admonitions always have title
+    # as first child)
+    title_node = node.children[0]
+    assert isinstance(title_node, nodes.title)
+    title_text = title_node.astext()
+    # All remaining children become nested blocks
+    content_children = node.children[1:]
+
+    block = UnoCallout(
+        text=text(text=title_text),
+        icon=Emoji(emoji="💬"),
+        color=BGColor.GRAY,
+    )
+
+    for child in content_children:
+        block.append(
+            blocks=_process_node_to_blocks(
+                child,
+                section_level=1,
+            )
+        )
+
+    return [block]
+
+
 @beartype
 @_process_node_to_blocks.register
 def _(

tests/test_integration.py

@@ -979,6 +979,52 @@ def test_admonition_with_bullet_points(
     )
 
 
+def test_generic_admonition(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+) -> None:
+    """Generic admonitions set callout text to the first line of the callout.
+
+    Generic admonitions require a title so are different from other
+    admonitions.
+    """
+    rst_content = """
+        .. admonition:: Important Information
+
+           This is the first paragraph.
+
+           This is the second paragraph.
+    """
+
+    callout = UnoCallout(
+        text=text(text="Important Information"),
+        icon=Emoji(emoji="💬"),
+        color=BGColor.GRAY,
+    )
+
+    nested_paragraph1 = UnoParagraph(
+        text=text(text="This is the first paragraph.")
+    )
+    nested_paragraph2 = UnoParagraph(
+        text=text(text="This is the second paragraph.")
+    )
+
+    callout.append(blocks=[nested_paragraph1])
+    callout.append(blocks=[nested_paragraph2])
+
+    expected_objects: list[Block] = [
+        callout,
+    ]
+
+    _assert_rst_converts_to_notion_objects(
+        rst_content=rst_content,
+        expected_objects=expected_objects,
+        make_app=make_app,
+        tmp_path=tmp_path,
+    )
+
+
 def test_nested_bullet_list(
     *,
     make_app: Callable[..., SphinxTestApp],