Merge pull request #286 from epinzur/esp/add_admonition_support

added admonition support for google docstrings

Author: machow

quartodoc/renderers/md_renderer.py

@@ -99,13 +99,13 @@ def _fetch_object_dispname(self, el: "dc.Alias | dc.Object"):
             return el.canonical_path
 
         raise ValueError(f"Unsupported display_name: `{self.display_name}`")
-    
+
     def _fetch_method_parameters(self, el: dc.Function):
         # adapted from mkdocstrings-python jinja tempalate
         if el.parent and el.parent.is_class and len(el.parameters) > 0:
             if el.parameters[0].name in {"self", "cls"}:
                 return dc.Parameters(*list(el.parameters)[1:])
-        
+
         return el.parameters
 
     def _render_table(self, rows, headers):
@@ -135,7 +135,7 @@ def render_annotation(self, el: expr.Name) -> str:
         # unescaped pipes screw up table formatting
         if self.render_interlinks:
             return f"[{sanitize(el.source)}](`{el.full}`)"
-        
+
         return sanitize(el.source)
 
     @dispatch
@@ -502,6 +502,20 @@ def render(self, el: ds.DocstringAttribute):
         ]
         return row
 
+    # admonition ----
+    # note this can be a see-also, warnings, or notes section
+    # from the googledoc standard
+    @dispatch
+    def render(self, el: ds.DocstringSectionAdmonition):
+        kind = el.title.lower()
+        if kind in ["notes", "warnings"]:
+            return el.value.description
+        elif kind == "see also":
+            # TODO: attempt to parse See Also sections
+            return convert_rst_link_to_md(el.value.description)
+
+        raise NotImplementedError(f"Unsupported DocstringSectionAdmonition kind: {kind}")
+
     # warnings ----
 
     @dispatch

quartodoc/tests/test_renderers.py

@@ -104,6 +104,19 @@ def test_render_doc_attribute(renderer):
     assert res == ["abc", r"Optional\[\]", "xyz"]
 
 
+def test_render_doc_section_admonition(renderer):
+    section = ds.DocstringSectionAdmonition(
+        kind="see also",
+        text="quartodoc.tests.example: Method for doing a thing",
+        title="See Also",
+    )
+
+    res = renderer.render(section)
+    print(res)
+
+    assert res == "quartodoc.tests.example: Method for doing a thing"
+
+
 @pytest.mark.parametrize("children", ["embedded", "flat"])
 def test_render_doc_module(snapshot, renderer, children):
     bp = blueprint(Auto(name="quartodoc.tests.example", children=children))