Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

fix: preserve underscores in docstring code spans (#11285)

Myles Scolnick5e8e83e4d9ce
diff --git a/marimo/_utils/docs.py b/marimo/_utils/docs.py
index 8f589d2b3a..9cb81c73eb 100644
--- a/marimo/_utils/docs.py
+++ b/marimo/_utils/docs.py
@@ -278,6 +278,25 @@ class MarimoConverter:
return False
+class MarkdownConverter:
+ # Let structured docstring converters handle RST, NumPy, and Google
+ # sections before preserving otherwise unrecognized Markdown verbatim.
+ priority = 0
+
+ def can_convert(self, docstring: str) -> bool:
+ return (
+ re.search(
+ r"(?<![\\`])(`+)(?!`)(.+?)(?<!`)\1(?!`)",
+ docstring,
+ flags=re.DOTALL,
+ )
+ is not None
+ )
+
+ def convert(self, docstring: str) -> str:
+ return docstring
+
+
def _process_code_block_content(description: str) -> str:
"""
Process a description that may contain code blocks and convert them to HTML.
diff --git a/pyproject.toml b/pyproject.toml
index 2bf5900ccc..6291c1b090 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -85,6 +85,7 @@ homepage = "https://github.com/marimo-team/marimo"
[project.entry-points."docstring_to_markdown"]
marimo_converter = "marimo._utils.docs:MarimoConverter"
+marimo_markdown_converter = "marimo._utils.docs:MarkdownConverter"
[project.optional-dependencies]
sql = [
diff --git a/tests/_utils/test_docs.py b/tests/_utils/test_docs.py
index 744c1e5a06..9c647e3a9e 100644
--- a/tests/_utils/test_docs.py
+++ b/tests/_utils/test_docs.py
@@ -1,6 +1,10 @@
+from unittest.mock import patch
+
+import pytest
from inline_snapshot import snapshot as inline_snapshot
from marimo._utils.docs import (
+ MarkdownConverter,
_process_code_block_content,
google_docstring_to_markdown,
)
@@ -9,6 +13,84 @@ from tests.mocks import snapshotter
snapshot = snapshotter(__file__)
[email protected]("with_args", [False, True])
+ "docstring",
+ [
+ """Add exclamation marks after text.
+
+Note: `shout_factor` supports all natural numbers.
+If a `shout_factor` is a negative number, that number of
+exclamation marks will be removed from the input text.
+
+For example: `shout('hi!!!', shout_factor=-1)` will return `'hi!!'`.""",
+ r"Use `a_b`, `[a_b]`, `*a_b*`, and `C:\some_path`.",
+ "Code:\n\n```python\nshout_factor = 1\n```",
+ "Use ``a`b_c`` to include a backtick.",
+ ],
+)
+def test_pylsp_docstring_code_spans(docstring: str, with_args: bool) -> None:
+ utils = pytest.importorskip("pylsp._utils")
+ if with_args:
+ docstring += (
+ "\n\nArgs:\n shout_factor: Number of exclamation marks."
+ )
+
+ assert utils.format_docstring(docstring, "markdown") == {
+ "kind": "markdown",
+ "value": (
+ google_docstring_to_markdown(docstring) if with_args else docstring
+ ),
+ }
+
+
+ "docstring",
+ [
+ "Use `shout_factor`.\n\n:param shout_factor: Number of exclamation marks.",
+ (
+ "Use `shout_factor`.\n\nParameters\n----------\n"
+ "shout_factor : int\n Number of exclamation marks."
+ ),
+ "Use :class:`My_Class`.",
+ "Use `shout_factor`.\n\n>>> shout_factor = 1\n>>> shout_factor\n1",
+ "Use shout_factor.",
+ "Use `shout_factor.",
+ r"Use \`shout_factor\`.",
+ "Plain text.",
+ "",
+ ],
+)
+def test_pylsp_preserves_other_docstring_formats(
+ docstring: str,
+) -> None:
+ utils = pytest.importorskip("pylsp._utils")
+ # Compare with the installed upstream version's behavior before our fallback.
+ with patch.object(MarkdownConverter, "can_convert", return_value=False):
+ expected = utils.format_docstring(docstring, "markdown")
+ assert utils.format_docstring(docstring, "markdown") == expected
+
+
+ ("docstring", "expected"),
+ [
+ ("", False),
+ ("Use `shout_factor`.", True),
+ ("Use ``shout_factor``.", True),
+ ("Use ``a`b_c``.", True),
+ ("Code:\n```python\nshout_factor = 1\n```", True),
+ ("Use shout_factor.", False),
+ ("Use `shout_factor.", False),
+ ("Use `shout_factor``.", False),
+ (r"Use \`shout_factor\`.", False),
+ ],
+)
+def test_markdown_converter_can_convert(
+ docstring: str, expected: bool
+) -> None:
+ assert MarkdownConverter().can_convert(docstring) is expected
+
+
def test_google_docstring_to_markdown_summary():
docstring = """This is the summary.