fix tests

hamelsmu · hamelsmu · commit baac169bc364 · 2023-08-18T09:31:16.000-07:00
diff --git a/.flake8 b/.flake8
@@ -8,3 +8,5 @@ ignore =
     W503,
     # redefinition of unused function name
     F811
+exclude =
+    test_*
diff --git a/quartodoc/renderers/md_renderer.py b/quartodoc/renderers/md_renderer.py
@@ -27,7 +27,6 @@ def _has_attr_section(el: dc.Docstring | None):
     return any([isinstance(x, ds.DocstringSectionAttributes) for x in el.parsed])
 
 
-
 class MdRenderer(Renderer):
     """Render docstrings to markdown.
 
@@ -66,8 +65,7 @@ def __init__(
         show_signature_annotations: bool = False,
         display_name: str = "relative",
         hook_pre=None,
-        use_interlinks = False,
-
+        use_interlinks=False,
     ):
         self.header_level = header_level
         self.show_signature = show_signature
@@ -79,14 +77,13 @@ def __init__(
         self.crnt_header_level = self.header_level
 
     @contextmanager
-    def _increment_header(self, n = 1):
+    def _increment_header(self, n=1):
         self.crnt_header_level += n
         try:
             yield
-        finally: 
+        finally:
             self.crnt_header_level -= n
 
-
     def _fetch_object_dispname(self, el: "dc.Alias | dc.Object"):
         # TODO: copied from Builder, should move into util function
         if self.display_name == "name":
@@ -101,13 +98,12 @@ def _fetch_object_dispname(self, el: "dc.Alias | dc.Object"):
             return el.canonical_path
 
         raise ValueError(f"Unsupported display_name: `{self.display_name}`")
-    
+
     def _render_table(self, rows, headers):
         table = tabulate(rows, headers=headers, tablefmt="github")
 
         return table
 
-
     # render_annotation method --------------------------------------------------------
 
     @dispatch
@@ -119,11 +115,11 @@ def render_annotation(self, el: str) -> str:
             An object representing a type annotation.
         """
         return el
-    
+
     @dispatch
     def render_annotation(self, el: None) -> str:
         return ""
-    
+
     @dispatch
     def render_annotation(self, el: expr.Name) -> str:
         # TODO: maybe there is a way to get tabulate to handle this?
@@ -142,18 +138,21 @@ def signature(self, el: dc.Alias, source: Optional[dc.Alias] = None):
         return self.signature(el.target, el)
 
     @dispatch
-    def signature(self, el: Union[dc.Class, dc.Function], source: Optional[dc.Alias] = None):
+    def signature(
+        self, el: Union[dc.Class, dc.Function], source: Optional[dc.Alias] = None
+    ):
         name = self._fetch_object_dispname(source or el)
         pars = self.render(el.parameters)
 
         return f"`{name}({pars})`"
 
     @dispatch
-    def signature(self, el: Union[dc.Module, dc.Attribute], source: Optional[dc.Alias] = None):
+    def signature(
+        self, el: Union[dc.Module, dc.Attribute], source: Optional[dc.Alias] = None
+    ):
         name = self._fetch_object_dispname(source or el)
         return f"`{name}`"
 
-
     @dispatch
     def render_header(self, el: layout.Doc):
         """Render the header of a docstring, including any anchors."""
@@ -164,7 +163,6 @@ def render_header(self, el: layout.Doc):
         _anchor = f"{{ #{el.obj.path} }}"
         return f"{'#' * self.crnt_header_level} {_str_dispname} {_anchor}"
 
-        
     # render method -----------------------------------------------------------
 
     @dispatch
@@ -199,7 +197,7 @@ def render(self, el: layout.Section):
             body = list(map(self.render, el.contents))
 
         return "\n\n".join([section_top, *body])
-    
+
     @dispatch
     def render(self, el: layout.Interlaced):
         # render a sequence of objects with like-sections together.
@@ -221,7 +219,6 @@ def render(self, el: layout.Interlaced):
         if first_doc.obj.docstring is None:
             raise ValueError("The first element of Interlaced must have a docstring.")
 
-        
         str_title = self.render_header(first_doc)
         str_sig = "\n\n".join(map(self.signature, objs))
         str_body = []
@@ -265,7 +262,6 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]):
             raw_meths = [x for x in el.members if x.obj.is_function]
             raw_classes = [x for x in el.members if x.obj.is_class]
 
-
             header = "| Name | Description |\n| --- | --- |"
 
             # attribute summary table ----
@@ -274,16 +270,16 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]):
             # TODO: for now, we skip making an attribute table on classes, unless
             # they contain an attributes section in the docstring
             if (
-                    raw_attrs
-                    and not _has_attr_section(el.obj.docstring)
-                    # TODO: what should backwards compat be?
-                    # and not isinstance(el, layout.DocClass)
-                ):
+                raw_attrs
+                and not _has_attr_section(el.obj.docstring)
+                # TODO: what should backwards compat be?
+                # and not isinstance(el, layout.DocClass)
+            ):
 
                 _attrs_table = "\n".join(map(self.summarize, raw_attrs))
                 attrs = f"{sub_header} Attributes\n\n{header}\n{_attrs_table}"
                 attr_docs.append(attrs)
-            
+
             # classes summary table ----
             if raw_classes:
                 _summary_table = "\n".join(map(self.summarize, raw_classes))
@@ -293,22 +289,29 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]):
 
                 n_incr = 1 if el.flat else 2
                 with self._increment_header(n_incr):
-                    class_docs.extend([self.render(x) for x in raw_classes if isinstance(x, layout.Doc)])
+                    class_docs.extend(
+                        [
+                            self.render(x)
+                            for x in raw_classes
+                            if isinstance(x, layout.Doc)
+                        ]
+                    )
 
             # method summary table ----
             if raw_meths:
                 _summary_table = "\n".join(map(self.summarize, raw_meths))
                 section_name = (
-                    "Methods" if isinstance(el, layout.DocClass)
-                    else "Functions"
+                    "Methods" if isinstance(el, layout.DocClass) else "Functions"
                 )
                 objs = f"{sub_header} {section_name}\n\n{header}\n{_summary_table}"
                 meth_docs.append(objs)
 
                 # TODO use context manager, or context variable?
                 n_incr = 1 if el.flat else 2
                 with self._increment_header(n_incr):
-                    meth_docs.extend([self.render(x) for x in raw_meths if isinstance(x, layout.Doc)])
+                    meth_docs.extend(
+                        [self.render(x) for x in raw_meths if isinstance(x, layout.Doc)]
+                    )
 
         body = self.render(el.obj)
         return "\n\n".join([title, body, *attr_docs, *class_docs, *meth_docs])
@@ -366,19 +369,24 @@ def render(self, el: dc.Parameters):
 
         # index for final positionly only args (via /)
         try:
-            pos_only = max([ii for ii, el in enumerate(el) if el.kind == dc.ParameterKind.positional_only])
+            pos_only = max(
+                [
+                    ii
+                    for ii, el in enumerate(el)
+                    if el.kind == dc.ParameterKind.positional_only
+                ]
+            )
         except ValueError:
             pos_only = None
 
-        
         pars = list(map(self.render, el))
 
         # insert a single `*,` argument to represent the shift to kw only arguments,
         # only if the shift to kw_only was not triggered by *args (var_positional)
         if (
             kw_only is not None
             and kw_only > 0
-            and el[kw_only-1].kind != dc.ParameterKind.var_positional
+            and el[kw_only - 1].kind != dc.ParameterKind.var_positional
         ):
             pars.insert(kw_only, sanitize("*"))
 
@@ -461,7 +469,7 @@ def render(self, el: ds.DocstringAttribute):
         row = [
             sanitize(el.name),
             self.render_annotation(el.annotation),
-            sanitize(el.description or "", allow_markdown=True)
+            sanitize(el.description or "", allow_markdown=True),
         ]
         return row
 
@@ -530,7 +538,6 @@ def render(self, el: Union[ds.DocstringReturn, ds.DocstringRaise]):
     def render(self, el):
         raise NotImplementedError(f"{type(el)}")
 
-    
     # Summarize ===============================================================
     # this method returns a summary description, such as a table summarizing a
     # layout.Section, or a row in the table for layout.Page or layout.DocFunction.
@@ -569,14 +576,16 @@ def summarize(self, el: layout.Section):
 
             str_func_table = "\n".join([thead, *rendered])
             return f"{header}\n\n{str_func_table}"
-        
+
         return header
 
     @dispatch
     def summarize(self, el: layout.Page):
         if el.summary is not None:
             # TODO: assumes that files end with .qmd
-            return self._summary_row(f"[{el.summary.name}]({el.path}.qmd)", el.summary.desc)
+            return self._summary_row(
+                f"[{el.summary.name}]({el.path}.qmd)", el.summary.desc
+            )
 
         if len(el.contents) > 1 and not el.flatten:
             raise ValueError(
@@ -591,16 +600,18 @@ def summarize(self, el: layout.Page):
     @dispatch
     def summarize(self, el: layout.MemberPage):
         # TODO: model should validate these only have a single entry
-        return self.summarize(el.contents[0], el.path, shorten = True)
-    
+        return self.summarize(el.contents[0], el.path, shorten=True)
+
     @dispatch
     def summarize(self, el: layout.Interlaced, *args, **kwargs):
         rows = [self.summarize(doc, *args, **kwargs) for doc in el.contents]
 
         return "\n".join(rows)
 
     @dispatch
-    def summarize(self, el: layout.Doc, path: Optional[str] = None, shorten: bool = False):
+    def summarize(
+        self, el: layout.Doc, path: Optional[str] = None, shorten: bool = False
+    ):
         if path is None:
             link = f"[{el.name}](#{el.anchor})"
         else:
@@ -612,8 +623,8 @@ def summarize(self, el: layout.Doc, path: Optional[str] = None, shorten: bool =
 
     @dispatch
     def summarize(self, el: layout.Link):
-         description = self.summarize(el.obj)
-         return self._summary_row(f"[](`{el.name}`)", description)
+        description = self.summarize(el.obj)
+        return self._summary_row(f"[](`{el.name}`)", description)
 
     @dispatch
     def summarize(self, obj: Union[dc.Object, dc.Alias]) -> str:
diff --git a/quartodoc/tests/__snapshots__/test_renderers.ambr b/quartodoc/tests/__snapshots__/test_renderers.ambr
@@ -12,10 +12,10 @@
   
   ## Parameters
   
-  | Name   | Type   | Description          | Default    |
-  |--------|--------|----------------------|------------|
-  | `x`    | str    | Uses signature type. | _required_ |
-  | `y`    | int    | Uses manual type.    | _required_ |
+  | Name   | Type         | Description          | Default    |
+  |--------|--------------|----------------------|------------|
+  | `x`    | [str](`str`) | Uses signature type. | _required_ |
+  | `y`    | [int](`int`) | Uses manual type.    | _required_ |
   
   ## Attributes
   
@@ -51,10 +51,10 @@
   
   ## Parameters
   
-  | Name   | Type   | Description          | Default    |
-  |--------|--------|----------------------|------------|
-  | `x`    | str    | Uses signature type. | _required_ |
-  | `y`    | int    | Uses manual type.    | _required_ |
+  | Name   | Type         | Description          | Default    |
+  |--------|--------------|----------------------|------------|
+  | `x`    | [str](`str`) | Uses signature type. | _required_ |
+  | `y`    | [int](`int`) | Uses manual type.    | _required_ |
   
   ## Attributes
   
@@ -87,11 +87,11 @@
   
   ## Attributes
   
-  | Name   | Type   | Description         |
-  |--------|--------|---------------------|
-  | x      | str    | Uses signature type |
-  | y      | int    | Uses manual type    |
-  | z      | float  | Defined in init     |
+  | Name   | Type             | Description         |
+  |--------|------------------|---------------------|
+  | x      | [str](`str`)     | Uses signature type |
+  | y      | [int](`int`)     | Uses manual type    |
+  | z      | [float](`float`) | Defined in init     |
   '''
 # ---
 # name: test_render_doc_module[embedded]
diff --git a/quartodoc/tests/test_renderers.py b/quartodoc/tests/test_renderers.py
@@ -25,8 +25,8 @@ def test_render_param_kwargs_annotated():
     res = renderer.render(f.parameters)
 
     assert (
-        res
-        == "a: \[int\](`int`), b: \[int\](`int`) = 1, *args: \[list\](`list`)\[\[str\](`str`)\], c: \[int\](`int`), d: \[int\](`int`), **kwargs: \[dict\](`dict`)\[\[str\](`str`), \[str\](`str`)\]"
+        res  # noqa: W605
+        == "a: \[int\](`int`), b: \[int\](`int`) = 1, *args: \[list\](`list`)\[\[str\](`str`)\], c: \[int\](`int`), d: \[int\](`int`), **kwargs: \[dict\](`dict`)\[\[str\](`str`), \[str\](`str`)\]"  # noqa: W605
     )
 
 
@@ -94,13 +94,14 @@ def test_render_doc_attribute(renderer):
     attr = ds.DocstringAttribute(
         name="abc",
         description="xyz",
-        annotation=exp.Expression(exp.Name("Optional", full="Optional"), "[", "]"),
+        annotation=exp.Expression(exp.Name("Optional[]", full="Optional")),
         value=1,
     )
 
     res = renderer.render(attr)
+    print(res)
 
-    assert res == ["abc", r"Optional\[\]", "xyz"]
+    assert res == ["abc", "[Optional\\[\\]](`Optional`)", "xyz"]  # noqa
 
 
 @pytest.mark.parametrize("children", ["embedded", "flat"])
