improvement: support more parameter descriptions, e.g. in polars

marimo/_dependencies/dependencies.py

@@ -200,7 +200,7 @@ class DependencyManager:
     vl_convert_python = Dependency("vl_convert")
     dotenv = Dependency("dotenv")
     docstring_to_markdown = Dependency(
-        "docstring_to_markdown", min_version="0.16.0"
+        "docstring_to_markdown", min_version="0.17.0"
     )
 
     # Version requirements to properly support the new superfences introduced in

marimo/_runtime/patches.py

@@ -307,13 +307,16 @@ def extract_docstring_to_markdown_arguments(
         for line in lines[start + 2 :]:
             if line.strip() == "" or line.startswith("#"):
                 continue
-            param_start = re.match(r"^\- `(.+)`: (.*)$", line.strip())
+            param_start = re.match(r"^\- `(.+)`:(?: (.*))?$", line.strip())
             if param_start:
                 param, first_line = param_start.groups()
-                param_descriptions[param] = first_line
+                param_descriptions[param] = first_line or ""
             else:
                 if param:
-                    param_descriptions[param] += "\n" + line.strip()
+                    if param_descriptions[param]:
+                        param_descriptions[param] += "\n" + line.strip()
+                    else:
+                        param_descriptions[param] = line.strip()
         return param_descriptions
 
     def py__doc__(self: ParamNameWrapper) -> str:

tests/_runtime/test_complete.py

@@ -2,6 +2,7 @@
 
 from inspect import signature
 from types import ModuleType
+from typing import Any
 
 import jedi
 import pytest
@@ -136,6 +137,18 @@ def collect_functions_to_check():
     return objects_to_check
 
 
+def dummy_func(arg1: str, arg2: str) -> None:
+    """
+    Parameters
+    ----------
+    arg1
+        polars often uses this format
+    arg2 : str, required
+        while other libraries prefer this format (which polars uses too)
+    """
+    del arg1, arg2
+
+
 @pytest.mark.skipif(
     not DependencyManager.docstring_to_markdown.has(),
     reason="docstring_to_markdown is not installed",
@@ -145,13 +158,14 @@ def collect_functions_to_check():
     [[obj, False] for obj in collect_functions_to_check()]
     + [
         # Test runtime inference for a subset of values
-        [marimo.accordion, True]
+        [marimo.accordion, True],
+        [dummy_func, False],
     ],
     ids=lambda obj: f"{obj}"
     if isinstance(obj, bool)
     else f"{obj.__module__}.{obj.__qualname__}",
 )
-def test_parameter_descriptions(obj, runtime_inference):
+def test_parameter_descriptions(obj: Any, runtime_inference: bool):
     patch_jedi_parameter_completion()
     import_name = obj.__module__
     marimo_export = obj.__name__
@@ -165,12 +179,14 @@ def test_parameter_descriptions(obj, runtime_inference):
             " is not yet supported by mkdocstrings for documentation rendering, see"
             " https://github.com/mkdocstrings/python/issues/135"
         )
+    if path.endswith("dummy_func"):
+        pytest.skip("Not picking up parameters for dummy_func")
     call = f"{path}("
     code = f"import {import_name};{call}"
     jedi.settings.auto_import_modules = ["marimo"] if runtime_inference else []
     script = jedi.Script(code=code)
-    completions = script.complete(line=1, column=len(code))
-    param_completions = {
+    completions: list[Any] = script.complete(line=1, column=len(code))
+    param_completions: dict[str, Any] = {
         completion.name[:-1]: completion
         for completion in completions
         if completion.name.endswith("=")