Merge pull request #292 from adamtheturtle/equation

Add support for maths equations

Author: adamtheturtle

README.rst

@@ -79,6 +79,17 @@ For TODO list support, also add the `sphinx-immaterial <https://github.com/jbms/
        "sphinx_notion",
    ]
 
+For mathematical equation support, also add the ``sphinx.ext.mathjax`` extension:
+
+.. code-block:: python
+
+   """Configuration for Sphinx."""
+
+   extensions = [
+       "sphinx.ext.mathjax",
+       "sphinx_notion",
+   ]
+
 PDF support is included by default with the sphinx-notionbuilder extension.
 
 Supported markup
@@ -101,6 +112,7 @@ The following syntax is supported:
 - Tables
 - Strikethrough text
 - Colored text and text styles (bold, italic, monospace)
+- Mathematical equations (inline and block-level)
 
 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>`_.
 
@@ -117,7 +129,7 @@ Audio files can be embedded using the ``audio`` directive. Both remote URLs and
 
 The audio will be rendered as an audio player in the generated Notion page.
 
-Using PDFs
+Using PDF
 ----------
 
 PDF files can be embedded using the ``pdf-include`` directive. Both remote URLs and local file paths are supported.
@@ -202,6 +214,45 @@ TODO lists with checkboxes can be created using the ``sphinx-immaterial.task_lis
 
 The checkboxes will be rendered as interactive TODO items in the generated Notion page, with completed tasks showing as checked and incomplete tasks as unchecked.
 
+Using Mathematical Equations
+-----------------------------
+
+Mathematical equations can be embedded using the ``sphinx.ext.mathjax`` extension.
+Both inline and block-level equations are supported:
+
+Inline Equations
+~~~~~~~~~~~~~~~~
+
+Inline equations can be written using the ``:math:`` role:
+
+.. code-block:: rst
+
+   This is an inline equation :math:`E = mc^2` in your text.
+
+   Here are some more examples:
+
+   - The quadratic formula: :math:`x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}`
+   - Euler's identity: :math:`e^{i\pi} + 1 = 0`
+
+Block Equations
+~~~~~~~~~~~~~~~
+
+Block-level equations can be written using the ``.. math::`` directive:
+
+.. code-block:: rst
+
+   .. math::
+
+      E = mc^2
+
+   The Schrödinger equation:
+
+   .. math::
+
+      i\hbar\frac{\partial}{\partial t}\Psi(\mathbf{r},t) = \hat{H}\Psi(\mathbf{r},t)
+
+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.
+
 Unsupported Notion Block Types
 ------------------------------
 
@@ -212,7 +263,6 @@ Unsupported Notion Block Types
 - Column and column list
 - Divider
 - Embed
-- Equation
 - File
 - Link preview
 - Mention

sample/conf.py

@@ -11,4 +11,5 @@
     "sphinx_toolbox.collapse",
     "atsphinx.audioplayer",
     "sphinx_immaterial.task_lists",
+    "sphinx.ext.mathjax",
 ]

sample/index.rst

@@ -474,6 +474,49 @@ Here's some text before the PDF.
 
 And here's some text after the PDF.
 
+Mathematical Equations
+~~~~~~~~~~~~~~~~~~~~~~
+
+The builder supports mathematical equations using the ``sphinx.ext.mathjax`` extension.
+
+Inline Equations
+~~~~~~~~~~~~~~~~
+
+You can include inline equations like this: :math:`E = mc^2` in your text.
+
+Here are some more examples:
+
+* The quadratic formula: :math:`x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}`
+* The integral of x squared: :math:`\int x^2 dx = \frac{x^3}{3} + C`
+* Euler's identity: :math:`e^{i\pi} + 1 = 0`
+
+Block Equations
+~~~~~~~~~~~~~~~
+
+You can also include block-level equations:
+
+.. math::
+
+   E = mc^2
+
+The Schrödinger equation:
+
+.. math::
+
+   i\hbar\frac{\partial}{\partial t}\Psi(\mathbf{r},t) = \hat{H}\Psi(\mathbf{r},t)
+
+Maxwell's equations:
+
+.. math::
+
+   \nabla \cdot \mathbf{E} = \frac{\rho}{\epsilon_0}
+
+   \nabla \cdot \mathbf{B} = 0
+
+   \nabla \times \mathbf{E} = -\frac{\partial \mathbf{B}}{\partial t}
+
+   \nabla \times \mathbf{B} = \mu_0\mathbf{J} + \mu_0\epsilon_0\frac{\partial \mathbf{E}}{\partial t}
+
 .. collapse:: Long code block
 
    .. code-block:: python

sample/spelling_wordlist.txt

@@ -1,3 +1,4 @@
 callout
 checkboxes
 reStructuredText
+Schrödinger

src/sphinx_notion/__init__.py

@@ -37,6 +37,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 Equation as UnoEquation
 from ultimate_notion.blocks import Heading as UnoHeading
 from ultimate_notion.blocks import (
     Heading1 as UnoHeading1,
@@ -66,7 +67,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, text
+from ultimate_notion.rich_text import Text, math, text
 
 _LOGGER = sphinx_logging.getLogger(name=__name__)
 
@@ -322,6 +323,15 @@ def _(child: nodes.paragraph) -> Text:
     return _create_styled_text_from_node(child=child)
 
 
+@beartype
+@_process_rich_text_node.register
+def _(child: nodes.math) -> Text:
+    """
+    Process math nodes by creating math rich text.
+    """
+    return math(expression=child.astext())
+
+
 @beartype
 def _create_styled_text_from_node(*, child: nodes.Element) -> Text:
     """Create styled text from a node with CSS class support.
@@ -1320,6 +1330,21 @@ def _(
     return []
 
 
+@beartype
+@_process_node_to_blocks.register
+def _(
+    node: nodes.math_block,
+    *,
+    section_level: int,
+) -> list[Block]:
+    """
+    Process math block nodes by creating Notion Equation blocks.
+    """
+    del section_level
+    latex_content = node.astext()
+    return [UnoEquation(latex=latex_content)]
+
+
 @beartype
 @_process_node_to_blocks.register
 def _(

tests/test_integration.py

@@ -21,6 +21,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 Equation as UnoEquation
 from ultimate_notion.blocks import (
     Heading1 as UnoHeading1,
 )
@@ -49,7 +50,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, text
+from ultimate_notion.rich_text import Text, math, text
 
 
 @beartype
@@ -2823,3 +2824,61 @@ def setup(app):
             tmp_path=tmp_path,
             conf_py_content=conf_py_content,
         )
+
+
+def test_inline_equation(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+) -> None:
+    """
+    Inline equations become Notion math rich text.
+    """
+    rst_content = """
+        This is an inline equation :math:`E = mc^2` in a paragraph.
+    """
+
+    normal_text1 = text(text="This is an inline equation ")
+    equation_text = math(expression="E = mc^2")
+    normal_text2 = text(text=" in a paragraph.")
+
+    combined_text = normal_text1 + equation_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", "sphinx.ext.mathjax"),
+    )
+
+
+def test_block_equation(
+    *,
+    make_app: Callable[..., SphinxTestApp],
+    tmp_path: Path,
+) -> None:
+    """
+    Block equations become Notion Equation blocks.
+    """
+    rst_content = """
+        .. math::
+
+           E = mc^2
+    """
+
+    expected_objects: list[Block] = [
+        UnoEquation(latex="E = mc^2"),
+    ]
+
+    _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.ext.mathjax"),
+    )