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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
fix: preserve underscores in docstring code spans (#11285)
Myles Scolnick5e8e83e4d9ce
diff --git a/marimo/_utils/docs.py b/marimo/_utils/docs.pyindex 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.tomlindex 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.pyindex 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 pytestfrom inline_snapshot import snapshot as inline_snapshotfrom marimo._utils.docs import (+ MarkdownConverter,_process_code_block_content,google_docstring_to_markdown,)@@ -9,6 +13,84 @@ from tests.mocks import snapshottersnapshot = 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.