Merge pull request #288 from adamtheturtle/rich-text-styles

Support more rich text styles

Author: adamtheturtle

README.rst

@@ -100,7 +100,7 @@ The following syntax is supported:
 - PDFs (with URLs or local paths)
 - Tables
 - Strikethrough text
-- Colored text
+- Colored text and text styles (bold, italic, monospace)
 
 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>`_.
 
@@ -130,10 +130,10 @@ PDF files can be embedded using the ``pdf-include`` directive. Both remote URLs
 
 The PDF will be rendered as an embedded PDF viewer in the generated Notion page.
 
-Using Colored Text
-------------------
+Using Text Styles
+-----------------
 
-Colored text can be added using the `sphinxcontrib-text-styles <https://sphinxcontrib-text-styles.readthedocs.io/>`_ extension. First, install the extension:
+Text styles can be added using the `sphinxcontrib-text-styles <https://sphinxcontrib-text-styles.readthedocs.io/>`_ extension. First, install the extension:
 
 .. code-block:: console
 
@@ -150,13 +150,39 @@ Then add it to your ``conf.py``:
        "sphinx_notion",
    ]
 
-You can then use colored text in your reStructuredText documents:
+You can then use various text styles in your reStructuredText documents:
+
+Text Colors
+~~~~~~~~~~~
 
 .. code-block:: rst
 
    This is :text-red:`red text`, :text-blue:`blue text`, and :text-green:`green text`.
 
-The following colors are supported: red, blue, green, yellow, orange, purple, pink, brown, and gray.
+The following text colors are supported: red, blue, green, yellow, orange, purple, pink, brown, and gray.
+
+Background Colors
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: rst
+
+   This is :bg-red:`red background text`, :bg-blue:`blue background text`, and :bg-green:`green background text`.
+
+The following background colors are supported: red, blue, green, yellow, orange, purple, pink, brown, and gray.
+
+Additional Text Styles
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: rst
+
+   This is :text-bold:`bold text`, :text-italic:`italic text`, :text-mono:`monospace text`, :text-strike:`strikethrough text`, and :text-underline:`underlined text`.
+
+The following additional text styles are supported:
+- ``:text-bold:`text`` - Makes text bold
+- ``:text-italic:`text`` - Makes text italic
+- ``:text-mono:`text`` - Makes text monospace
+- ``:text-strike:`text`` - Makes text strikethrough
+- ``:text-underline:`text`` - Makes text underlined
 
 Using TODO Lists
 ----------------

sample/index.rst

@@ -30,6 +30,11 @@ The builder also supports background colors using `sphinxcontrib-text-styles <ht
 
 This is :bg-red:`red background text`, :bg-blue:`blue background text`, :bg-green:`green background text`, :bg-yellow:`yellow background text`, :bg-orange:`orange background text`, :bg-purple:`purple background text`, :bg-pink:`pink background text`, :bg-brown:`brown background text`, and :bg-gray:`gray background text`.
 
+Other Text Styles
+~~~~~~~~~~~~~~~~~~
+
+The builder supports additional text styles: :text-bold:`bold text`, :text-italic:`italic text`, :text-mono:`monospace text`, :text-strike:`strikethrough text`, and :text-underline:`underlined text`.
+
 .. note::
 
    This is an important note that demonstrates the note admonition support.

sample/notion-sha-mapping.json

@@ -1,6 +1,6 @@
 {
-  "10be79a09f2b92602ce383a0455f9fe6268f6792decba9383ddce53fded08137": "2829ce7b-60a4-814e-892c-ec3e68051237",
-  "822e7aef5ac028d8cf5565420b59a1f3286a0af6fa17d6f0c617151a1f386507": "2829ce7b-60a4-816a-9324-e6c531c8ea88",
-  "cd765602a4632f5abb325a66ce59aef506e84fdb6e4fe5590c634f4db567ef2c": "2829ce7b-60a4-81ac-9cc6-c7b7c6db359f",
-  "eeeca6a7b26d982c4de616bc3bf36b9f40fb090938081cb828709920613dae72": "2829ce7b-60a4-81ec-bf6c-d003b291168e"
+  "10be79a09f2b92602ce383a0455f9fe6268f6792decba9383ddce53fded08137": "2829ce7b-60a4-8121-9bed-c1e6a78ac799",
+  "822e7aef5ac028d8cf5565420b59a1f3286a0af6fa17d6f0c617151a1f386507": "2829ce7b-60a4-81ef-87a3-cab67ceaf773",
+  "cd765602a4632f5abb325a66ce59aef506e84fdb6e4fe5590c634f4db567ef2c": "2829ce7b-60a4-8140-bf23-d049a1ca8e76",
+  "eeeca6a7b26d982c4de616bc3bf36b9f40fb090938081cb828709920613dae72": "2829ce7b-60a4-813b-a1c9-f5a595dcadec"
 }

src/_notion_scripts/upload.py

@@ -51,7 +51,7 @@ def _clean_deleted_blocks_from_mapping(
     sha_to_block_id: dict[str, str],
     session: Session,
 ) -> dict[str, str]:
-    """Remove deleted blocks from SHA mapping.
+    """Remove deleted blocks from ``SHA`` mapping.
 
     Returns a new dictionary with only existing blocks.
     """

src/sphinx_notion/__init__.py

@@ -110,12 +110,11 @@ def _get_background_color_classes() -> set[str]:
 
 
 @beartype
-def _color_from_node(*, node: nodes.inline) -> Color | None:
+def _color_from_css_classes(*, classes: list[str]) -> Color | None:
     """Extract Notion color from CSS classes.
 
     Classes created by ``sphinxcontrib-text-styles``.
     """
-    classes = node.attributes.get("classes", [])
     color_mapping = _get_text_color_mapping()
 
     for css_class in classes:
@@ -126,12 +125,13 @@ def _color_from_node(*, node: nodes.inline) -> Color | None:
 
 
 @beartype
-def _background_color_from_node(*, node: nodes.inline) -> BGColor | None:
+def _background_color_from_css_classes(
+    *, classes: list[str]
+) -> BGColor | None:
     """Extract Notion background color from CSS classes.
 
     Classes created by ``sphinxcontrib-text-styles``.
     """
-    classes = node.attributes.get("classes", [])
     bg_color_mapping: dict[str, BGColor] = {
         "bg-red": BGColor.RED,
         "bg-blue": BGColor.BLUE,
@@ -228,61 +228,76 @@ def _create_rich_text_from_children(*, node: nodes.Element) -> Text:
             )
         elif isinstance(child, nodes.target):
             continue
-        elif isinstance(child, nodes.inline):
-            bg_color = _background_color_from_node(node=child)
-            text_color = _color_from_node(node=child)
-
-            classes = child.attributes.get("classes", [])
-            color_mapping = _get_text_color_mapping()
-            bg_color_classes = _get_background_color_classes()
-
-            for css_class in classes:
-                if (
-                    css_class not in color_mapping
-                    and css_class not in bg_color_classes
-                ):
-                    _LOGGER.warning(
-                        "Unsupported text style classes: %s. "
-                        "Text will be rendered without styling.",
-                        css_class,
-                    )
-
-            color: BGColor | Color | None = bg_color or text_color
-            new_text = text(
-                text=child.astext(),
-                bold=isinstance(child, nodes.strong),
-                italic=isinstance(child, nodes.emphasis),
-                code=isinstance(child, nodes.literal),
-                strikethrough=isinstance(child, strike_node),
-                # Ignore the type check here because Ultimate Notion has
-                # a bad type hint: https://github.com/ultimate-notion/ultimate-notion/issues/140
-                color=color,  # type: ignore[arg-type]  # pyright: ignore[reportArgumentType]
-            )
         elif isinstance(child, nodes.title_reference):
             # We match the behavior of the HTML builder here.
             # If you render ``A `B``` in HTML, it will render as
             # ``A <i>B</i>``.
-            new_text = text(
-                text=child.astext(),
-                italic=True,
-            )
+            new_text = text(text=child.astext(), italic=True)
+        elif isinstance(child, nodes.Text):
+            new_text = text(text=child.astext())
         elif isinstance(
             child,
             (
-                nodes.Text,
+                nodes.inline,
                 nodes.strong,
                 nodes.emphasis,
                 nodes.literal,
                 strike_node,
                 nodes.paragraph,
             ),
         ):
+            classes = child.attributes.get("classes", [])
+            bg_color = _background_color_from_css_classes(classes=classes)
+            text_color = _color_from_css_classes(classes=classes)
+
+            color_mapping = _get_text_color_mapping()
+            bg_color_classes = _get_background_color_classes()
+
+            is_bold = isinstance(child, nodes.strong) or "text-bold" in classes
+            is_italic = (
+                isinstance(child, nodes.emphasis) or "text-italic" in classes
+            )
+            is_code = (
+                isinstance(child, nodes.literal) or "text-mono" in classes
+            )
+            is_strikethrough = (
+                isinstance(child, strike_node) or "text-strike" in classes
+            )
+            is_underline = "text-underline" in classes
+
+            supported_style_classes = {
+                "text-bold",
+                "text-italic",
+                "text-mono",
+                "text-strike",
+                "text-underline",
+                *color_mapping.keys(),
+                *bg_color_classes,
+            }
+            unsupported_styles = [
+                css_class
+                for css_class in classes
+                if css_class not in supported_style_classes
+            ]
+
+            if unsupported_styles:
+                _LOGGER.warning(
+                    "Unsupported text style classes: %s. "
+                    "Text will be rendered without styling.",
+                    ", ".join(unsupported_styles),
+                )
+
+            color: BGColor | Color | None = bg_color or text_color
             new_text = text(
                 text=child.astext(),
-                bold=isinstance(child, nodes.strong),
-                italic=isinstance(child, nodes.emphasis),
-                code=isinstance(child, nodes.literal),
-                strikethrough=isinstance(child, strike_node),
+                bold=is_bold,
+                italic=is_italic,
+                code=is_code,
+                strikethrough=is_strikethrough,
+                underline=is_underline,
+                # Ignore the type check here because Ultimate Notion has
+                # a bad type hint: https://github.com/ultimate-notion/ultimate-notion/issues/140
+                color=color,  # type: ignore[arg-type]  # pyright: ignore[reportArgumentType]
             )
         else:
             unsupported_child_type_msg = (

tests/test_integration.py

@@ -49,7 +49,7 @@
 from ultimate_notion.blocks import Video as UnoVideo
 from ultimate_notion.file import ExternalFile
 from ultimate_notion.obj_api.enums import BGColor, CodeLang, Color
-from ultimate_notion.rich_text import text
+from ultimate_notion.rich_text import Text, text
 
 
 @beartype
@@ -2315,28 +2315,28 @@ def test_individual_colors(
     )
 
 
-def test_text_styles_non_color(
+def test_text_styles_unsupported_color(
     *,
     make_app: Callable[..., SphinxTestApp],
     tmp_path: Path,
 ) -> None:
     """
-    Non-color text styles (like underline) emit a warning.
+    Unsupported colors from ``sphinxcontrib-text-styles`` emit warnings.
     """
     rst_content = """
-        This is :text-underline:`underlined text`.
+        This is :text-cyan:`cyan text`.
     """
 
     expected_warning = (
-        "Unsupported text style classes: text-underline. "
+        "Unsupported text style classes: text-cyan. "
         "Text will be rendered without styling."
     )
 
     normal_text = text(text="This is ")
-    underline_text = text(text="underlined text")
+    cyan_text = text(text="cyan text")
     normal_text2 = text(text=".")
 
-    combined_text = normal_text + underline_text + normal_text2
+    combined_text = normal_text + cyan_text + normal_text2
 
     expected_paragraph = UnoParagraph(text=combined_text)
 
@@ -2440,6 +2440,49 @@ def test_text_styles_and_strike(
     )
 
 
+@pytest.mark.parametrize(
+    argnames=("role", "expected_text"),
+    argvalues=[
+        ("text-bold", text(text="text-bold text", bold=True)),
+        ("text-italic", text(text="text-italic text", italic=True)),
+        ("text-mono", text(text="text-mono text", code=True)),
+        ("text-strike", text(text="text-strike text", strikethrough=True)),
+        ("text-underline", text(text="text-underline text", underline=True)),
+    ],
+)
+def test_additional_text_styles(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+    role: str,
+    expected_text: Text,
+) -> None:
+    """
+    Additional text styles from the ``sphinxcontrib_text_styles`` extension are
+    supported.
+    """
+    rst_content = f"""
+        This is :{role}:`{role} text`.
+    """
+
+    normal_text1 = text(text="This is ")
+    normal_text2 = text(text=".")
+
+    combined_text = normal_text1 + expected_text + normal_text2
+
+    expected_paragraph = UnoParagraph(text=combined_text)
+
+    expected_objects: list[Block] = [expected_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", "sphinxcontrib_text_styles"),
+    )
+
+
 def test_flat_task_list(
     *,
     make_app: Callable[..., SphinxTestApp],