Merge pull request #36 from machow/refactor-renderer

refactor(renderer)!: change to_md method name to render

Author: machow

docs/get-started/basic-docs.qmd

@@ -39,7 +39,7 @@ renderer = MdRenderer()
 
 doc_parts = obj.docstring.parsed
 doc_params = [entry for entry in doc_parts if entry.kind.name == "parameters"][0]
-print(renderer.to_md(doc_params))
+print(renderer.render(doc_params))
 ```
 
 ## Section options

docs/get-started/renderers.qmd

@@ -98,34 +98,34 @@ class SomeRenderer:
         self.header_level = header_level
 
     @dispatch
-    def visit(self, el):
+    def render(self, el):
         raise NotImplementedError(f"Unsupported type: {type(el)}")
 
     @dispatch
-    def visit(self, el: Union[dc.Alias, dc.Object]):
+    def render(self, el: Union[dc.Alias, dc.Object]):
         header = "#" * self.header_level
         str_header = f"{header} {el.name}"
         str_params = f"N PARAMETERS: {len(el.parameters)}"
-        str_sections = "SECTIONS: " + self.visit(el.docstring)
+        str_sections = "SECTIONS: " + self.render(el.docstring)
         
         # return something pretty
         return "\n".join([str_header, str_params, str_sections])
 
     @dispatch
-    def visit(self, el: dc.Docstring):
+    def render(self, el: dc.Docstring):
         return f"A docstring with {len(el.parsed)} pieces"
 
 
 f_obj = get_object("quartodoc", "get_object")
 
-print(SomeRenderer(header_level=2).visit(f_obj))
+print(SomeRenderer(header_level=2).render(f_obj))
 ```
 
 Note 3 big pieces:
 
-* **Generic dispatch**: The plum `dispatch` function decorates each `visit` method. The type annotations
-  specify the types of data each version of visit should dispatch on.
-* **Default behavior**: The first `visit` method ensures a `NotImplementedError` is raised by default.
-* **Tree walking**: `visit` methods often call `visit` again on sub elements.
+* **Generic dispatch**: The plum `dispatch` function decorates each `render` method. The type annotations
+  specify the types of data each version of render should dispatch on.
+* **Default behavior**: The first `render` method ensures a `NotImplementedError` is raised by default.
+* **Tree walking**: `render` methods often call `render` again on sub elements.
 
 

examples/shiny/_renderer.py

@@ -30,8 +30,8 @@ class Renderer(MdRenderer):
     style = "shiny"
 
     @dispatch
-    def to_md(self, el: Union[dc.Object, dc.Alias]):
-        rendered = super().to_md(el)
+    def render(self, el: Union[dc.Object, dc.Alias]):
+        rendered = super().render(el)
 
         p_example = SHINY_PATH / "examples" / el.name / "app.py"
         if p_example.exists():

quartodoc/autosummary.py

@@ -311,10 +311,9 @@ def render_item_link(self, obj):
     def write_doc_pages(self):
         """Write individual function documentation pages."""
 
-        # TODO: rename to_md to render or something
         for item in self.items.values():
             _log.info(f"Rendering `{item.canonical_path}`")
-            rendered = self.renderer.to_md(item)
+            rendered = self.renderer.render(item)
             html_path = Path(self.fetch_object_uri(item))
             html_path.parent.mkdir(exist_ok=True, parents=True)
 
@@ -410,7 +409,7 @@ class BuilderSinglePage(Builder):
     style = "single-page"
 
     def render_index(self):
-        return "\n\n".join([self.renderer.to_md(item) for item in self.items.values()])
+        return "\n\n".join([self.renderer.render(item) for item in self.items.values()])
 
     def fetch_object_uri(self, obj):
         index_name = Path(self.out_index).with_suffix(".html")

quartodoc/renderers.py

@@ -76,7 +76,7 @@ def convert_rst_link_to_md(rst):
     return re.sub(expr, r"[](\1)", rst, flags=re.MULTILINE)
 
 
-# to_md -----------------------------------------------------------------------
+# render -----------------------------------------------------------------------
 # griffe function dataclass structure:
 #   Object:
 #     kind: Kind {"module", "class", "function", "attribute"}
@@ -155,7 +155,7 @@ class MdRenderer(Renderer):
     >>> from quartodoc import MdRenderer, get_object
     >>> renderer = MdRenderer(header_level=2)
     >>> f = get_object("quartodoc", "get_object")
-    >>> print(renderer.to_md(f)[:81])
+    >>> print(renderer.render(f)[:81])
     ## get_object
     `get_object(module: str, object_name: str, parser: str = 'numpy')`
 
@@ -201,25 +201,25 @@ def _fetch_object_dispname(self, el: "dc.Alias | dc.Object"):
         raise ValueError(f"Unsupported display_name: `{self.display_name}`")
 
     @dispatch
-    def to_md(self, el):
+    def render(self, el):
         raise NotImplementedError(f"Unsupported type: {type(el)}")
 
     @dispatch
-    def to_md(self, el: str):
+    def render(self, el: str):
         return el
 
     # TODO: remove, as this is now handled by _render_annotation
     # @dispatch
-    # def to_md(self, el: Union[Expression, Name]):
+    # def render(self, el: Union[Expression, Name]):
     #    # these are used often for annotations, and full returns it as a string
     #    return el.full
 
     @dispatch
-    def to_md(self, el: Union[dc.Object, dc.Alias]):
+    def render(self, el: Union[dc.Object, dc.Alias]):
         # TODO: replace hard-coded header level
 
         _str_dispname = self._fetch_object_dispname(el)
-        _str_pars = self.to_md(el.parameters)
+        _str_pars = self.render(el.parameters)
         str_sig = f"`{_str_dispname}({_str_pars})`"
 
         _anchor = f"{{ #{_str_dispname} }}"
@@ -232,7 +232,7 @@ def to_md(self, el: Union[dc.Object, dc.Alias]):
             for section in el.docstring.parsed:
                 new_el = docstring_section_narrow(section)
                 title = new_el.kind.value
-                body = self.to_md(new_el)
+                body = self.render(new_el)
 
                 if title != "text":
                     header = f"{'#' * (self.header_level + 1)} {title.title()}"
@@ -248,17 +248,17 @@ def to_md(self, el: Union[dc.Object, dc.Alias]):
         return "\n\n".join(parts)
 
     @dispatch
-    def to_md(self, el: dc.Attribute):
+    def render(self, el: dc.Attribute):
         raise NotImplementedError()
 
     # signature parts -------------------------------------------------------------
 
     @dispatch
-    def to_md(self, el: dc.Parameters):
-        return ", ".join(map(self.to_md, el))
+    def render(self, el: dc.Parameters):
+        return ", ".join(map(self.render, el))
 
     @dispatch
-    def to_md(self, el: dc.Parameter):
+    def render(self, el: dc.Parameter):
         # TODO: missing annotation
         splats = {dc.ParameterKind.var_keyword, dc.ParameterKind.var_positional}
         has_default = el.default and el.kind not in splats
@@ -280,24 +280,24 @@ def to_md(self, el: dc.Parameter):
     # note this can be a number of things. for example, opening docstring text,
     # or a section with a header not included in the numpydoc standard
     @dispatch
-    def to_md(self, el: ds.DocstringSectionText):
+    def render(self, el: ds.DocstringSectionText):
         new_el = docstring_section_narrow(el)
         if isinstance(new_el, ds.DocstringSectionText):
             # ensures we don't recurse forever
             return el.value
 
-        return self.to_md(new_el)
+        return self.render(new_el)
 
     # parameters ----
 
     @dispatch
-    def to_md(self, el: ds.DocstringSectionParameters):
-        rows = list(map(self.to_md, el.value))
+    def render(self, el: ds.DocstringSectionParameters):
+        rows = list(map(self.render, el.value))
         header = ["Name", "Type", "Description", "Default"]
         return tabulate(rows, header, tablefmt="github")
 
     @dispatch
-    def to_md(self, el: ds.DocstringParameter) -> Tuple[str]:
+    def render(self, el: ds.DocstringParameter) -> Tuple[str]:
         # TODO: if default is not, should return the word "required" (unescaped)
         default = "required" if el.default is None else escape(el.default)
 
@@ -307,56 +307,56 @@ def to_md(self, el: ds.DocstringParameter) -> Tuple[str]:
     # attributes ----
 
     @dispatch
-    def to_md(self, el: ds.DocstringSectionAttributes):
+    def render(self, el: ds.DocstringSectionAttributes):
         header = ["Name", "Type", "Description"]
-        rows = list(map(self.to_md, el.value))
+        rows = list(map(self.render, el.value))
 
         return tabulate(rows, header, tablefmt="github")
 
     @dispatch
-    def to_md(self, el: ds.DocstringAttribute):
+    def render(self, el: ds.DocstringAttribute):
         annotation = self._render_annotation(el.annotation)
-        return el.name, self.to_md(annotation), el.description
+        return el.name, self.render(annotation), el.description
 
     # see also ----
 
     @dispatch
-    def to_md(self, el: DocstringSectionSeeAlso):
+    def render(self, el: DocstringSectionSeeAlso):
         # TODO: attempt to parse See Also sections
         return convert_rst_link_to_md(el.value)
 
     # examples ----
 
     @dispatch
-    def to_md(self, el: ds.DocstringSectionExamples):
+    def render(self, el: ds.DocstringSectionExamples):
         # its value is a tuple: DocstringSectionKind["text" | "examples"], str
         data = map(tuple_to_data, el.value)
-        return "\n\n".join(list(map(self.to_md, data)))
+        return "\n\n".join(list(map(self.render, data)))
 
     @dispatch
-    def to_md(self, el: ExampleCode):
+    def render(self, el: ExampleCode):
         return f"""```python
 {el.value}
 ```"""
 
     # returns ----
 
     @dispatch
-    def to_md(self, el: Union[ds.DocstringSectionReturns, ds.DocstringSectionRaises]):
-        rows = list(map(self.to_md, el.value))
+    def render(self, el: Union[ds.DocstringSectionReturns, ds.DocstringSectionRaises]):
+        rows = list(map(self.render, el.value))
         header = ["Type", "Description"]
         return tabulate(rows, header, tablefmt="github")
 
     @dispatch
-    def to_md(self, el: Union[ds.DocstringReturn, ds.DocstringRaise]):
+    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)
 
     # unsupported parts ----
 
     @dispatch
-    def to_md(self, el: ExampleText):
+    def render(self, el: ExampleText):
         return el.value
 
     @dispatch.multi(
@@ -367,5 +367,5 @@ def to_md(self, el: ExampleText):
         (ds.DocstringReceive,),
         (ds.DocstringAttribute,),
     )
-    def to_md(self, el):
+    def render(self, el):
         raise NotImplementedError(f"{type(el)}")

quartodoc/tests/tests.py

@@ -11,9 +11,9 @@ def test_get_function():
     )
 
 
-def test_render_to_md():
+def test_renderer_render():
     # TODO: use snapshots?
     f_obj = get_function("quartodoc", "get_function")
 
     renderer = MdRenderer()
-    assert isinstance(renderer.to_md(f_obj), str)
+    assert isinstance(renderer.render(f_obj), str)