Merge pull request #309 from adamtheturtle/embed

Add support for sphinx-iframes

Author: adamtheturtle

README.rst

@@ -42,18 +42,29 @@ For video support, also add the `sphinxcontrib-video <https://sphinxcontrib-vide
    """Configuration for Sphinx."""
 
    extensions = [
-       "sphinxcontrib.video",  # Must be before sphinx_notion
+       # ``sphinxcontrib.video`` must be before ``sphinx_notion``
+       "sphinxcontrib.video",
        "sphinx_notion",
    ]
 
+If you are using ``sphinxcontrib.video`` with ``sphinx-iframes``, the warning ``app.add_directive`` will be raised.
+This is because ``sphinxcontrib.video`` and ``sphinx-iframes`` both implement a ``video`` directive.
+To suppress this warning, add the following to your ``conf.py``:
+
+.. code-block:: python
+
+   """Configuration for Sphinx."""
+
+   suppress_warnings = ["app.add_directive"]
+
 For strikethrough text support, also add the `sphinxnotes-strike <https://github.com/sphinx-toolbox/sphinxnotes-strike>`_ extension:
 
 .. code-block:: python
 
    """Configuration for Sphinx."""
 
    extensions = [
-       "sphinxnotes.strike",  # Must be before sphinx_notion
+       "sphinxnotes.strike",  # Must be before ``sphinx_notion``
        "sphinx_notion",
    ]
 
@@ -115,12 +126,13 @@ The following syntax is supported:
 - Table of contents
 - 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)
+- Collapsible sections (using the ``collapse`` directive from ``sphinx-toolbox``)
+- Rest-example blocks (using the ``rest-example`` directive from ``sphinx-toolbox``)
 - Images (with URLs or local paths)
 - Videos (with URLs or local paths)
 - Audio (with URLs or local paths)
 - PDFs (with URLs or local paths)
+- Embed blocks (using the ``iframe`` directive from ``sphinx-iframes``)
 - Tables
 - Strikethrough text
 - Colored text and text styles (bold, italic, monospace)
@@ -156,6 +168,43 @@ Both remote URLs and local file paths are supported.
 
 The PDF will be rendered as an embedded PDF viewer in the generated Notion page.
 
+Using Embed Blocks
+------------------
+
+Embed blocks can be created using the `sphinx-iframes <https://pypi.org/project/sphinx-iframes/>`_ extension. First, install the extension:
+
+.. code-block:: console
+
+   $ pip install sphinx-iframes
+
+Then add it to your ``conf.py``:
+
+.. code-block:: python
+
+   """Configuration for Sphinx."""
+
+   extensions = [
+       "sphinx_iframes",  # Must be before ``sphinx_notion``
+       "sphinx_notion",
+   ]
+
+You can then use the ``iframe`` directive:
+
+.. code-block:: rst
+
+   .. iframe:: https://www.youtube.com/embed/dQw4w9WgXcQ
+
+The iframes will be rendered as embed blocks in the generated Notion page, allowing you to embed external content like videos, interactive demos, or other web content.
+However, if you are using ``sphinx-iframes`` with ``sphinxcontrib.video``, the warning ``app.add_directive`` will be raised.
+This is because ``sphinx-iframes`` and ``sphinxcontrib.video`` both implement a ``video`` directive.
+To suppress this warning, add the following to your ``conf.py``:
+
+.. code-block:: python
+
+   """Configuration for Sphinx."""
+
+   suppress_warnings = ["app.add_directive"]
+
 Using Text Styles
 -----------------
 
@@ -282,7 +331,6 @@ Unsupported Notion Block Types
 - Child page
 - Column and column list
 - Divider
-- Embed
 - File
 - Link preview
 - Mention

pyproject.toml

@@ -33,6 +33,7 @@ dynamic = [
 dependencies = [
     "atsphinx-audioplayer>=0.1.0",
     "beartype>=0.21.0",
+    "beautifulsoup4>=4.13.3",
     "click>=8.0.0",
     "docutils>=0.21",
     "requests>=2.32.5",
@@ -74,6 +75,7 @@ optional-dependencies.dev = [
     # use it to lint shell commands in GitHub workflow files.
     "shellcheck-py==0.11.0.1",
     "shfmt-py==3.12.0.2",
+    "sphinx-iframes==1.0.7",
     "sphinx-lint==1.0.0",
     "sphinx-pyproject==0.3.0",
     "sphinx-substitution-extensions==2025.6.6",
@@ -86,6 +88,7 @@ optional-dependencies.dev = [
 ]
 optional-dependencies.release = [ "check-wheel-contents==0.6.3" ]
 optional-dependencies.sample = [
+    "sphinx-iframes==1.0.7",
     "sphinxcontrib-text-styles==0.2.0",
 ]
 urls.Source = "https://github.com/adamtheturtle/sphinx-notionbuilder"
@@ -415,6 +418,7 @@ ignore_names = [
     "rst_prolog",
     "source_suffix",
     "spelling_word_list_filename",
+    "suppress_warnings",
     "templates_path",
     "warning_is_error",
     # Docutils translator

sample/conf.py

@@ -4,13 +4,19 @@
 
 extensions = [
     "sphinxcontrib.video",
+    "sphinx_iframes",
+    "sphinx_notion",
     "sphinxnotes.strike",
     "sphinxcontrib_text_styles",
-    "sphinx_notion",
     "sphinx_simplepdf",
     "sphinx_toolbox.collapse",
     "sphinx_toolbox.rest_example",
     "atsphinx.audioplayer",
     "sphinx_immaterial.task_lists",
     "sphinx.ext.mathjax",
 ]
+
+# This is necessary because ``sphinx-iframes`` and ``sphinxcontrib.video``
+# both implement a ``video`` directive.
+# This is explained in the README.
+suppress_warnings = ["app.add_directive"]

sample/index.rst

@@ -336,3 +336,10 @@ This is useful for documentation that demonstrates how to write reStructuredText
 
 
       greet(name="World")
+
+Embed Blocks
+~~~~~~~~~~~~
+
+Embed blocks can be created using the `sphinx-iframes <https://pypi.org/project/sphinx-iframes/>`_ extension.
+
+.. iframe:: https://www.youtube.com/embed/dQw4w9WgXcQ

src/sphinx_notion/__init__.py

@@ -9,6 +9,7 @@
 from pathlib import Path
 from typing import Any
 
+import bs4
 import sphinxnotes.strike
 from atsphinx.audioplayer.nodes import (  # pyright: ignore[reportMissingTypeStubs]
     audio as audio_node,
@@ -27,6 +28,7 @@
 )
 from sphinx_toolbox.collapse import CollapseNode
 from sphinxcontrib.video import (  # pyright: ignore[reportMissingTypeStubs]
+    Video,
     video_node,
 )
 from sphinxnotes.strike import strike_node
@@ -37,6 +39,7 @@
 from ultimate_notion.blocks import BulletedItem as UnoBulletedItem
 from ultimate_notion.blocks import Callout as UnoCallout
 from ultimate_notion.blocks import Code as UnoCode
+from ultimate_notion.blocks import Embed as UnoEmbed
 from ultimate_notion.blocks import Equation as UnoEquation
 from ultimate_notion.blocks import Heading as UnoHeading
 from ultimate_notion.blocks import (
@@ -614,6 +617,26 @@ def _map_pygments_to_notion_language(*, pygments_lang: str) -> CodeLang:
     return language_mapping[pygments_lang.lower()]
 
 
+def _get_unsupported_node_type_exception(
+    *,
+    node: nodes.Element,
+) -> NotImplementedError:
+    """
+    Raise an ``NotImplementedError`` for an unsupported node type.
+    """
+    line_number = node.line or node.parent.line
+    source = node.source or node.parent.source
+
+    if line_number is not None and source is not None:
+        unsupported_node_type_msg = (
+            f"Unsupported node type: {node.tagname} on line "
+            f"{line_number} in {source}."
+        )
+    else:
+        unsupported_node_type_msg = f"Unsupported node type: {node.tagname}."
+    return NotImplementedError(unsupported_node_type_msg)
+
+
 @singledispatch
 @beartype
 def _process_node_to_blocks(
@@ -625,12 +648,7 @@ def _process_node_to_blocks(
     Required function for ``singledispatch``.
     """
     del section_level
-    unsupported_node_type_msg = (
-        f"Unsupported node type: {node.tagname} on line "
-        f"{node.line or node.parent.line} in "
-        f"{node.source or node.parent.source}."
-    )
-    raise NotImplementedError(unsupported_node_type_msg)
+    raise _get_unsupported_node_type_exception(node=node)
 
 
 @beartype
@@ -1354,6 +1372,32 @@ def _(
     return blocks
 
 
+@beartype
+@_process_node_to_blocks.register
+def _(
+    node: nodes.raw,
+    *,
+    section_level: int,
+) -> list[Block]:
+    """
+    Process raw nodes, specifically those containing HTML from the extension
+    ``sphinx-iframes``.
+    """
+    del section_level
+
+    # Check if this is an ``iframe`` from ``sphinx-iframes``.
+    # See https://github.com/TeachBooks/sphinx-iframes/issues/9
+    # for making this more robust.
+    soup = bs4.BeautifulSoup(markup=node.rawsource, features="html.parser")
+    iframe = soup.find(name="iframe")
+    if iframe is not None:
+        url = iframe.get(key="src")
+        assert url is not None
+        return [UnoEmbed(url=str(object=url))]
+
+    raise _get_unsupported_node_type_exception(node=node)
+
+
 @beartype
 def _process_rest_example_container(
     *,
@@ -1546,6 +1590,14 @@ def _filter_ulem(record: logging.LogRecord) -> bool:
     return msg != "latex package 'ulem' already included"
 
 
+@beartype
+def _make_static_dir(app: Sphinx) -> None:
+    """
+    We make the ``_static`` directory that ``sphinx-iframes`` expects.
+    """
+    (app.outdir / "_static").mkdir(parents=True, exist_ok=True)
+
+
 @beartype
 def setup(app: Sphinx) -> ExtensionMetadata:
     """
@@ -1559,8 +1611,18 @@ def setup(app: Sphinx) -> ExtensionMetadata:
         callback=_notion_register_pdf_include_directive,
     )
 
+    app.connect(event="builder-inited", callback=_make_static_dir)
+
     logger = logging.getLogger(name="sphinx.sphinx.registry")
     logger.addFilter(filter=_filter_ulem)
 
     sphinxnotes.strike.SUPPORTED_BUILDERS.append(NotionBuilder)
+
+    # that we use. The ``sphinx-iframes`` extension implements a ``video``
+    # directive that we don't use.
+    # Make sure that if they are both enabled, we use the
+    # ``sphinxcontrib.video`` extension.
+    if "sphinxcontrib.video" in app.extensions:
+        app.add_directive(name="video", cls=Video, override=True)
+
     return {"parallel_read_safe": True}