Merge pull request #84 from adamtheturtle/toggle-support

Add toggle support

Author: adamtheturtle

README.rst

@@ -24,6 +24,17 @@ Add the following to ``conf.py`` to enable the extension:
 
    extensions = ["sphinx_notion"]
 
+For collapsible sections (toggle blocks), also add the sphinx-toolbox collapse extension:
+
+.. code-block:: python
+
+   """Configuration for Sphinx."""
+
+   extensions = [
+       "sphinx_notion",
+       "sphinx_toolbox.collapse",
+   ]
+
 Supported markup
 ----------------
 
@@ -35,6 +46,7 @@ The following syntax is supported:
 - Table of contents
 - Block quotes
 - Note, warning, and tip admonitions
+- Collapsible sections (using sphinx-toolbox collapse directive)
 
 See a `sample document source <https://raw.githubusercontent.com/adamtheturtle/sphinx-notionbuilder/refs/heads/main/sample/index.rst>`_ and the `published Notion page <https://www.notion.so/Sphinx-Notionbuilder-Sample-2579ce7b60a48142a556d816c657eb55>`_.
 

pyproject.toml

@@ -36,6 +36,7 @@ dependencies = [
     "docutils>=0.21",
     "notion-client>=2.0.0",
     "sphinx>=8.2.3",
+    "sphinx-toolbox>=4.0.0",
     "ultimate-notion>=0.8",
 ]
 optional-dependencies.dev = [

sample/conf.py

@@ -2,4 +2,7 @@
 Configuration for Sphinx.
 """
 
-extensions = ["sphinx_notion"]
+extensions = [
+    "sphinx_notion",
+    "sphinx_toolbox.collapse",
+]

sample/index.rst

@@ -35,6 +35,38 @@ This is **bold** and *italic* and ``inline code``.
 
    This is a helpful tip that demonstrates the tip admonition support.
 
+.. collapse:: Click to expand this section
+
+   This content is hidden by default and can be expanded by clicking the toggle.
+
+   It supports **all the same formatting** as regular content:
+
+   * Bullet points
+   * ``Code snippets``
+   * *Emphasis* and **bold text**
+
+   .. note::
+
+      You can even nest admonitions inside collapsible sections!
+
+   .. code-block:: python
+
+      """Run code within a collapse."""
+
+
+      def example_function() -> str:
+          """Example code inside a collapsed section."""
+          return "This is hidden by default"
+
+
+      example_function()
+
+.. collapse:: Another collapsible section
+
+   You can have multiple collapsible sections in your document.
+
+   Each one can contain different types of content.
+
 .. code-block:: python
 
    """Python code."""

src/sphinx_notion/__init__.py

@@ -12,6 +12,7 @@
 from sphinx.application import Sphinx
 from sphinx.builders.text import TextBuilder
 from sphinx.util.typing import ExtensionMetadata
+from sphinx_toolbox.collapse import CollapseNode
 from ultimate_notion import Emoji
 from ultimate_notion.blocks import BulletedItem as UnoBulletedItem
 from ultimate_notion.blocks import Callout as UnoCallout
@@ -35,6 +36,9 @@
 from ultimate_notion.blocks import (
     TableOfContents as UnoTableOfContents,
 )
+from ultimate_notion.blocks import (
+    ToggleItem as UnoToggleItem,
+)
 from ultimate_notion.core import NotionObject
 from ultimate_notion.obj_api.core import GenericObject
 from ultimate_notion.obj_api.enums import CodeLang, Color
@@ -304,6 +308,32 @@ def _(node: nodes.tip, *, section_level: int) -> list[NotionObject[Any]]:
     return _create_admonition_callout(node=node, emoji="💡", color=Color.GREEN)
 
 
+@_process_node_to_blocks.register
+def _(node: CollapseNode, *, section_level: int) -> list[NotionObject[Any]]:
+    """
+    Process collapse nodes by creating Notion ToggleItem blocks.
+    """
+    del section_level
+
+    children_to_process = node.children
+    title_text = node.attributes["label"]
+    toggle_block = UnoToggleItem(text=title_text)
+
+    for child in children_to_process:
+        for child_block in list(
+            _process_node_to_blocks(
+                child,
+                section_level=1,
+            )
+        ):
+            # Add nested blocks as children to the toggle
+            # Remove pyright ignore once we have
+            # https://github.com/ultimate-notion/ultimate-notion/issues/94.
+            toggle_block.obj_ref.value.children.append(child_block.obj_ref)  # pyright: ignore[reportUnknownMemberType]
+
+    return [toggle_block]
+
+
 def _map_pygments_to_notion_language(*, pygments_lang: str) -> CodeLang:
     """
     Map ``Pygments`` language names to Notion CodeLang ``enum`` values.
@@ -540,6 +570,18 @@ def visit_tip(self, node: nodes.Element) -> None:
 
         raise nodes.SkipNode
 
+    def visit_CollapseNode(self, node: nodes.Element) -> None:  # pylint: disable=invalid-name  # noqa: N802
+        """
+        Handle collapse nodes by creating Notion ToggleItem blocks.
+        """
+        blocks = _process_node_to_blocks(
+            node,
+            section_level=self._section_level,
+        )
+        self._blocks.extend(blocks)
+
+        raise nodes.SkipNode
+
     def visit_document(self, node: nodes.Element) -> None:
         """
         Initialize block collection at document start.
@@ -584,4 +626,5 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     """
     app.add_builder(builder=NotionBuilder)
     app.set_translator(name="notion", translator_class=NotionTranslator)
+
     return {"parallel_read_safe": True}

tests/test_integration.py

@@ -32,6 +32,9 @@
 from ultimate_notion.blocks import (
     TableOfContents as UnoTableOfContents,
 )
+from ultimate_notion.blocks import (
+    ToggleItem as UnoToggleItem,
+)
 from ultimate_notion.core import NotionObject
 from ultimate_notion.obj_api.core import GenericObject
 from ultimate_notion.obj_api.enums import CodeLang, Color
@@ -62,12 +65,14 @@ def _assert_rst_converts_to_notion_objects(
     expected_objects: list[NotionObject[Any]],
     make_app: Callable[..., SphinxTestApp],
     tmp_path: Path,
+    extensions: tuple[str, ...] = ("sphinx_notion",),
 ) -> None:
     """
     The given rST content is converted to the given expected objects.
     """
     srcdir = tmp_path / "src"
     srcdir.mkdir()
+
     (srcdir / "conf.py").write_text(data="")
 
     cleaned_content = textwrap.dedent(text=rst_content).strip()
@@ -77,7 +82,7 @@ def _assert_rst_converts_to_notion_objects(
         srcdir=srcdir,
         builddir=tmp_path / "build",
         buildername="notion",
-        confoverrides={"extensions": ["sphinx_notion"]},
+        confoverrides={"extensions": list(extensions)},
     )
     app.build()
 
@@ -1007,3 +1012,51 @@ def test_nested_bullet_list_error_on_excessive_depth(
             make_app=make_app,
             tmp_path=tmp_path,
         )
+
+
+def test_collapse_block(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+) -> None:
+    """
+    Test that collapse directives convert to Notion ToggleItem blocks.
+    """
+    rst_content = """
+        Regular paragraph.
+
+        .. collapse:: Click to expand
+
+           This content is hidden by default.
+
+           It supports **formatting**.
+
+        Another paragraph.
+    """
+
+    toggle_block = UnoToggleItem(text="Click to expand")
+
+    nested_para1 = UnoParagraph(text="This content is hidden by default.")
+    nested_para2 = UnoParagraph(text="It supports formatting.")
+    nested_para2.rich_text = (
+        text(text="It supports ", bold=False)
+        + text(text="formatting", bold=True)
+        + text(text=".", bold=False)
+    )
+
+    toggle_block.obj_ref.value.children.append(nested_para1.obj_ref)  # pyright: ignore[reportUnknownMemberType]
+    toggle_block.obj_ref.value.children.append(nested_para2.obj_ref)  # pyright: ignore[reportUnknownMemberType]
+
+    expected_objects: list[NotionObject[Any]] = [
+        UnoParagraph(text="Regular paragraph."),
+        toggle_block,
+        UnoParagraph(text="Another paragraph."),
+    ]
+
+    _assert_rst_converts_to_notion_objects(
+        rst_content=rst_content,
+        expected_objects=expected_objects,
+        make_app=make_app,
+        tmp_path=tmp_path,
+        extensions=("sphinx_notion", "sphinx_toolbox.collapse"),
+    )