fix: do not sanitize interlinks in table descriptions

Author: machow

quartodoc/autosummary.py

@@ -99,6 +99,10 @@ def get_object(
     >>> get_function("quartodoc", "get_function")
     <Function('get_function', ...
 
+    Returns
+    -------
+    x:
+        abc
     """
 
     if object_name is not None:

quartodoc/renderers/base.py

@@ -10,13 +10,16 @@ def escape(val: str):
     return f"`{val}`"
 
 
-def sanitize(val: str):
-    return (
-        val.replace("\n", " ")
-        .replace("|", "\\|")
-        .replace("[", "\\[")
-        .replace("]", "\\]")
-    )
+def sanitize(val: str, allow_markdown=False):
+    # sanitize common tokens that break tables
+    res = val.replace("\n", " ").replace("|", "\\|")
+
+    # sanitize elements that can get interpreted as markdown links
+    # or citations
+    if not allow_markdown:
+        return res.replace("[", "\\[").replace("]", "\\]")
+
+    return res
 
 
 def convert_rst_link_to_md(rst):

quartodoc/renderers/md_renderer.py

@@ -419,7 +419,8 @@ def render(self, el: ds.DocstringParameter) -> Tuple[str]:
         default = "required" if el.default is None else escape(el.default)
 
         annotation = self.render_annotation(el.annotation)
-        return (escape(el.name), annotation, sanitize(el.description), default)
+        clean_desc = sanitize(el.description, allow_markdown=True)
+        return (escape(el.name), annotation, clean_desc, default)
 
     # attributes ----
 
@@ -436,7 +437,7 @@ def render(self, el: ds.DocstringAttribute):
         row = [
             sanitize(el.name),
             self.render_annotation(annotation),
-            sanitize(el.description or "")
+            sanitize(el.description or "", allow_markdown=True)
         ]
         return row
 
@@ -490,7 +491,7 @@ def render(self, el: Union[ds.DocstringSectionReturns, ds.DocstringSectionRaises
     def render(self, el: Union[ds.DocstringReturn, ds.DocstringRaise]):
         # similar to DocstringParameter, but no name or default
         annotation = self.render_annotation(el.annotation)
-        return (annotation, el.description)
+        return (annotation, sanitize(el.description, allow_markdown=True))
 
     # unsupported parts ----
 
@@ -512,7 +513,7 @@ def render(self, el):
 
     @staticmethod
     def _summary_row(link, description):
-        return f"| {link} | {sanitize(description)} |"
+        return f"| {link} | {sanitize(description, allow_markdown=True)} |"
 
     @dispatch
     def summarize(self, el):

quartodoc/tests/test_renderers.py

@@ -1,10 +1,9 @@
 import pytest
+import griffe.docstrings.dataclasses as ds
 
 from quartodoc.renderers import MdRenderer
 from quartodoc import get_object
 
-# TODO: tests in test_basic.py also use the renderer, so we should move them here.
-
 
 @pytest.fixture
 def renderer():
@@ -44,3 +43,20 @@ def test_render_param_kwonly(src, dst, renderer):
 
     res = renderer.render(f.parameters)
     assert res == dst
+
+
+@pytest.mark.parametrize(
+    "pair",
+    [
+        [ds.DocstringSectionParameters, ds.DocstringParameter],
+        [ds.DocstringSectionAttributes, ds.DocstringAttribute],
+        [ds.DocstringSectionReturns, ds.DocstringReturn],
+    ],
+)
+def test_render_table_description_interlink(renderer, pair):
+    interlink = "[](`abc`)"
+    cls_section, cls_par = pair
+    pars = cls_section([cls_par(name="x", description=interlink)])
+
+    res = renderer.render(pars)
+    assert interlink in res