Merge pull request #180 from adamtheturtle/add-numbered-list-support

Add support for numbered lists

Author: adamtheturtle

sample/index.rst

@@ -158,6 +158,25 @@ Some key features:
 * Supports images with URLs
 * Supports videos with URLs and local files
 
+Numbered Lists
+~~~~~~~~~~~~~~
+
+The builder now supports numbered lists:
+
+1. First numbered item
+2. Second numbered item with **bold text**
+3. Third numbered item with nested content
+
+   1. First nested numbered item
+   2. Second nested numbered item
+
+      1. Deeply nested numbered item
+      2. Another deeply nested item
+
+   3. Back to second level
+
+4. Fourth top-level item
+
 Heading 2 with *italic*
 -----------------------
 

src/sphinx_notion/__init__.py

@@ -33,6 +33,7 @@
     Heading3 as UnoHeading3,
 )
 from ultimate_notion.blocks import Image as UnoImage
+from ultimate_notion.blocks import NumberedItem as UnoNumberedItem
 from ultimate_notion.blocks import (
     Paragraph as UnoParagraph,
 )
@@ -343,6 +344,44 @@ def _process_list_item_recursively(
                     parent_path=[*parent_path, (block, id(block))],
                 )
 
+    @beartype
+    def _process_numbered_list_item_recursively(
+        self,
+        *,
+        node: nodes.list_item,
+        parent_path: list[tuple[Block, int]],
+    ) -> None:
+        """
+        Recursively process a numbered list item node and return a
+        NumberedItem.
+        """
+        paragraph = node.children[0]
+        assert isinstance(paragraph, nodes.paragraph)
+        rich_text = _create_rich_text_from_children(node=paragraph)
+        block = UnoNumberedItem(text=rich_text)
+        self._add_block_to_tree(
+            block=block,
+            parent_path=parent_path,
+        )
+
+        numbered_only_msg = (
+            "The only thing Notion supports within a numbered list is a "
+            f"numbered list. Given {type(node).__name__} on line {node.line} "
+            f"in {node.source}"
+        )
+        assert isinstance(node, nodes.list_item)
+
+        for child in node.children[1:]:
+            assert isinstance(child, nodes.enumerated_list), numbered_only_msg
+            for nested_list_item in child.children:
+                assert isinstance(nested_list_item, nodes.list_item), (
+                    numbered_only_msg
+                )
+                self._process_numbered_list_item_recursively(
+                    node=nested_list_item,
+                    parent_path=[*parent_path, (block, id(block))],
+                )
+
     @singledispatchmethod
     @beartype
     def _process_node_to_blocks(  # pylint: disable=no-self-use
@@ -476,6 +515,30 @@ def _(
                 parent_path=parent_path,
             )
 
+    @_process_node_to_blocks.register
+    def _(
+        self,
+        node: nodes.enumerated_list,
+        *,
+        section_level: int,
+        parent_path: list[tuple[Block, int]],
+    ) -> None:
+        """
+        Process enumerated list nodes by creating Notion NumberedItem blocks.
+        """
+        del section_level
+        numbered_only_msg = (
+            "The only thing Notion supports within a numbered list is a "
+            f"numbered list. Given {type(node).__name__} on line {node.line} "
+            f"in {node.source}"
+        )
+        for list_item in node.children:
+            assert isinstance(list_item, nodes.list_item), numbered_only_msg
+            self._process_numbered_list_item_recursively(
+                node=list_item,
+                parent_path=parent_path,
+            )
+
     @_process_node_to_blocks.register
     def _(
         self,
@@ -836,6 +899,18 @@ def visit_bullet_list(self, node: nodes.Element) -> None:
 
         raise nodes.SkipNode
 
+    def visit_enumerated_list(self, node: nodes.Element) -> None:
+        """
+        Handle enumerated list nodes by processing each list item.
+        """
+        self._process_node_to_blocks(
+            node,
+            section_level=self._section_level,
+            parent_path=[],
+        )
+
+        raise nodes.SkipNode
+
     def visit_topic(self, node: nodes.Element) -> None:
         """
         Handle topic nodes, specifically for table of contents.

tests/test_integration.py

@@ -27,6 +27,7 @@
     Heading3 as UnoHeading3,
 )
 from ultimate_notion.blocks import Image as UnoImage
+from ultimate_notion.blocks import NumberedItem as UnoNumberedItem
 from ultimate_notion.blocks import (
     Paragraph as UnoParagraph,
 )
@@ -64,6 +65,7 @@ def _reconstruct_nested_structure(
             "paragraph",
             "callout",
             "bulleted_list_item",
+            "numbered_list_item",
             "toggle",
         }:
             children = item.get("children", [])
@@ -1041,6 +1043,122 @@ def test_nested_bullet_list(
     )
 
 
+def test_flat_numbered_list(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+) -> None:
+    """
+    Flat numbered lists become separate Notion NumberedItem blocks.
+    """
+    rst_content = """
+        1. First numbered point
+        2. Second numbered point
+        3. Third numbered point with longer text
+    """
+    expected_objects: list[Block] = [
+        UnoNumberedItem(text=text(text="First numbered point")),
+        UnoNumberedItem(text=text(text="Second numbered point")),
+        UnoNumberedItem(
+            text=text(text="Third numbered point with longer text")
+        ),
+    ]
+    _assert_rst_converts_to_notion_objects(
+        rst_content=rst_content,
+        expected_objects=expected_objects,
+        make_app=make_app,
+        tmp_path=tmp_path,
+    )
+
+
+def test_numbered_list_with_inline_formatting(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+) -> None:
+    """
+    Numbered lists preserve inline formatting in rich text.
+    """
+    rst_content = """
+        1. This is **bold text** in a numbered list
+    """
+    numbered_item = UnoNumberedItem(
+        text=(
+            text(text="This is ", bold=False, italic=False, code=False)
+            + text(text="bold text", bold=True, italic=False, code=False)
+            + text(
+                text=" in a numbered list",
+                bold=False,
+                italic=False,
+                code=False,
+            )
+        )
+    )
+
+    expected_objects: list[Block] = [
+        numbered_item,
+    ]
+
+    _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_numbered_list(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+) -> None:
+    """
+    Deeply nested numbered lists create hierarchical block structures.
+    """
+    rst_content = """
+        1. Top level item
+        2. Top level with children
+
+           1. Second level item
+           2. Second level with children
+
+              1. Third level item (now allowed!)
+
+        3. Another top level item
+    """
+
+    third_level_1 = UnoNumberedItem(
+        text=text(text="Third level item (now allowed!)")
+    )
+
+    second_level_1 = UnoNumberedItem(text=text(text="Second level item"))
+    second_level_2 = UnoNumberedItem(
+        text=text(text="Second level with children")
+    )
+
+    top_level_1 = UnoNumberedItem(text=text(text="Top level item"))
+    top_level_2 = UnoNumberedItem(text=text(text="Top level with children"))
+
+    second_level_2.append(blocks=[third_level_1])
+    top_level_2.append(blocks=[second_level_1])
+    top_level_2.append(blocks=[second_level_2])
+
+    top_level_3 = UnoNumberedItem(text=text(text="Another top level item"))
+
+    expected_objects: list[Block] = [
+        top_level_1,
+        top_level_2,
+        top_level_3,
+    ]
+
+    _assert_rst_converts_to_notion_objects(
+        rst_content=rst_content,
+        expected_objects=expected_objects,
+        make_app=make_app,
+        tmp_path=tmp_path,
+    )
+
+
 def test_collapse_block(
     *,
     make_app: Callable[..., SphinxTestApp],