Merge pull request #302 from adamtheturtle/rest-example-support

Support rest example extension

Author: adamtheturtle

README.rst

@@ -90,6 +90,17 @@ For mathematical equation support, also add the ``sphinx.ext.mathjax`` extension
        "sphinx_notion",
    ]
 
+For rest-example blocks support, also add the `sphinx-toolbox <https://sphinx-toolbox.readthedocs.io/>`_ rest-example extension:
+
+.. code-block:: python
+
+   """Configuration for Sphinx."""
+
+   extensions = [
+       "sphinx_toolbox.rest_example",
+       "sphinx_notion",
+   ]
+
 PDF support is included by default with the sphinx-notionbuilder extension.
 
 Supported markup
@@ -105,6 +116,7 @@ The following syntax is supported:
 - Block quotes
 - All standard admonitions (note, warning, tip, attention, caution, danger, error, hint, important)
 - Collapsible sections (using sphinx-toolbox collapse directive)
+- Rest-example blocks (using sphinx-toolbox rest-example directive)
 - Images (with URLs or local paths)
 - Videos (with URLs or local paths)
 - Audio (with URLs or local paths)
@@ -254,6 +266,11 @@ Block-level equations can be written using the ``.. math::`` directive:
 
 The equations will be rendered as proper mathematical notation in the generated Notion page, with inline equations appearing within the text flow and block equations appearing as separate equation blocks.
 
+Using Rest-Example Blocks
+-------------------------
+
+Rest-example blocks can be created using the `sphinx_toolbox.rest_example <https://sphinx-toolbox.readthedocs.io/en/stable/extensions/rest_example.html>`_ extension to create example blocks that show both source code and expected output. These are rendered as callout blocks in Notion with nested code blocks:
+
 Unsupported Notion Block Types
 ------------------------------
 

sample/conf.py

@@ -9,6 +9,7 @@
     "sphinx_notion",
     "sphinx_simplepdf",
     "sphinx_toolbox.collapse",
+    "sphinx_toolbox.rest_example",
     "atsphinx.audioplayer",
     "sphinx_immaterial.task_lists",
     "sphinx.ext.mathjax",

sample/index.rst

@@ -420,3 +420,23 @@ The Schrödinger equation:
 .. math::
 
    i\hbar\frac{\partial}{\partial t}\Psi(\mathbf{r},t) = \hat{H}\Psi(\mathbf{r},t)
+
+Rest Examples
+~~~~~~~~~~~~~
+
+The `sphinx-toolbox rest_example extension <https://sphinx-toolbox.readthedocs.io/en/stable/extensions/rest_example.html>`_ allows you to show both the reStructuredText source code and its rendered output side by side.
+This is useful for documentation that demonstrates how to write reStructuredText directives.
+
+.. rest-example::
+
+   .. code-block:: python
+
+      """Python code."""
+
+
+      def greet(name: str) -> str:
+          """Return a greeting message."""
+          return f"Hello, {name}!"
+
+
+      greet(name="World")

src/sphinx_notion/__init__.py

@@ -578,6 +578,9 @@ def _map_pygments_to_notion_language(*, pygments_lang: str) -> CodeLang:
         "reason": CodeLang.REASON,
         "ruby": CodeLang.RUBY,
         "rb": CodeLang.RUBY,
+        # This is not a perfect match, but at least rest-example will
+        # be rendered.
+        "rest": CodeLang.PLAIN_TEXT,
         "rust": CodeLang.RUST,
         "rs": CodeLang.RUST,
         "sass": CodeLang.SASS,
@@ -711,10 +714,25 @@ def _(
     *,
     section_level: int,
 ) -> list[Block]:
+    """Process paragraph nodes by creating Notion Paragraph blocks.
+
+    Special case: if the paragraph contains only a container a
+    ``rest-example`` class, process the container directly instead of
+    trying to process it as rich text.
     """
-    Process paragraph nodes by creating Notion Paragraph blocks.
-    """
-    del section_level
+    if (
+        len(node.children) == 1
+        and isinstance(
+            node.children[0],
+            nodes.container,
+        )
+        and node.children[0].attributes.get("classes", []) == ["rest-example"]
+    ):
+        return _process_node_to_blocks(
+            node.children[0],
+            section_level=section_level,
+        )
+
     rich_text = _create_rich_text_from_children(node=node)
     return [UnoParagraph(text=rich_text)]
 
@@ -1293,7 +1311,7 @@ def _(
     section_level: int,
 ) -> list[Block]:
     """
-    Process container nodes, especially for ``literalinclude`` with captions.
+    Process container nodes.
     """
     num_children_for_captioned_literalinclude = 2
     if (
@@ -1320,6 +1338,13 @@ def _(
             )
         ]
 
+    classes = node.attributes.get("classes", [])
+    if classes == ["rest-example"]:
+        return _process_rest_example_container(
+            node=node,
+            section_level=section_level,
+        )
+
     blocks: list[Block] = []
     for child in node.children:
         child_blocks = _process_node_to_blocks(
@@ -1329,6 +1354,38 @@ def _(
     return blocks
 
 
+@beartype
+def _process_rest_example_container(
+    *,
+    node: nodes.container,
+    section_level: int,
+) -> list[Block]:
+    """
+    Process a ``rest-example`` container by creating nested callout blocks.
+    """
+    rst_source_node = node.children[0]
+    assert isinstance(rst_source_node, nodes.literal_block)
+    output_nodes = node.children[1:]
+    code_blocks = _process_node_to_blocks(rst_source_node, section_level=1)
+
+    output_blocks: list[Block] = []
+    for output_node in output_nodes:
+        output_blocks.extend(
+            _process_node_to_blocks(output_node, section_level=section_level)
+        )
+
+    code_callout = UnoCallout(text=text(text="Code"))
+    code_callout.append(blocks=code_blocks)
+
+    output_callout = UnoCallout(text=text(text="Output"))
+    output_callout.append(blocks=output_blocks)
+
+    main_callout = UnoCallout(text=text(text="Example"))
+    main_callout.append(blocks=[code_callout, output_callout])
+
+    return [main_callout]
+
+
 @beartype
 @_process_node_to_blocks.register
 def _(
@@ -1360,6 +1417,21 @@ def _(
     return [UnoEquation(latex=latex_content)]
 
 
+@beartype
+@_process_node_to_blocks.register
+def _(
+    node: nodes.target,
+    *,
+    section_level: int,
+) -> list[Block]:
+    """
+    Process target nodes by ignoring them completely.
+    """
+    del node
+    del section_level
+    return []
+
+
 @beartype
 @_process_node_to_blocks.register
 def _(

tests/test_integration.py

@@ -2935,3 +2935,80 @@ def test_block_equation(
         tmp_path=tmp_path,
         extensions=("sphinx_notion", "sphinx.ext.mathjax"),
     )
+
+
+def test_rest_example_block(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+) -> None:
+    """
+    Rest example blocks become Notion callout blocks with nested code and
+    description.
+    """
+    rst_content = """
+        .. rest-example::
+
+           .. code-block:: python
+
+              def hello_world():
+                  print("Hello, World!")
+
+           Rendered output shows what the code does.
+    """
+
+    code_callout = UnoCallout(
+        text=text(text="Code"),
+    )
+    code_callout.append(
+        blocks=[
+            UnoCode(
+                text=text(
+                    text=textwrap.dedent(
+                        text="""\
+                        .. code-block:: python
+
+                           def hello_world():
+                               print("Hello, World!")
+
+                        Rendered output shows what the code does."""
+                    )
+                ),
+                language="plain text",
+            ),
+        ]
+    )
+
+    output_callout = UnoCallout(
+        text=text(text="Output"),
+    )
+    output_callout.append(
+        blocks=[
+            UnoCode(
+                text=text(
+                    text=textwrap.dedent(
+                        text="""\
+                        def hello_world():
+                            print("Hello, World!")""",
+                    )
+                ),
+                language="python",
+            ),
+            UnoParagraph(
+                text=text(text="Rendered output shows what the code does.")
+            ),
+        ]
+    )
+
+    main_callout = UnoCallout(text=text(text="Example"))
+    main_callout.append(blocks=[code_callout, output_callout])
+
+    expected_objects: list[Block] = [main_callout]
+
+    _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.rest_example"),
+    )