got admonitions working

python/docs/_renderer.py

@@ -2,7 +2,6 @@
 
 import quartodoc.ast as qast
 
-from contextlib import contextmanager
 from griffe.docstrings import dataclasses as ds
 from griffe import dataclasses as dc
 from tabulate import tabulate
@@ -19,6 +18,14 @@
 except ImportError:
     from griffe import dataclasses as expr
 
+skip_annotation_types = [
+    "kaskada",
+    "kaskada.destination",
+    "kaskada.results",
+    "kaskada.windows",
+    "pyarrow",
+]
+
 
 def _has_attr_section(el: dc.Docstring | None):
     if el is None:
@@ -117,19 +124,26 @@ def _render_table(self, rows, headers):
 
     @dispatch
     def render_annotation(self, el: str) -> str:
+        print(f"render str: {el}")
         return sanitize(el)
 
     @dispatch
     def render_annotation(self, el: None) -> str:
+        print("render none")
         return ""
 
     @dispatch
     def render_annotation(self, el: expr.Name) -> str:
-        return f"[{sanitize(el.source)}](`{el.full}`)"
+        print(f"render name: {el} {el.full}")
+        if el.full not in skip_annotation_types:
+            return f"[{sanitize(el.source)}](`{el.full}`)"
+        return ""
 
     @dispatch
     def render_annotation(self, el: expr.Expression) -> str:
-        return "".join(map(self.render_annotation, el))
+        print(f"render expr: {el}")
+        text = "".join(map(self.render_annotation, el))
+        return text.lstrip(".")
 
     # signature method --------------------------------------------------------
 
@@ -301,7 +315,7 @@ def render(self, el: dc.Parameters):
 
     @dispatch
     def render(self, el: dc.Parameter):
-        print(f'Parameter: {el}')
+        print(f'Parameter: {el} anno: {el.annotation}')
         # TODO: missing annotation
         splats = {dc.ParameterKind.var_keyword, dc.ParameterKind.var_positional}
         has_default = el.default and el.kind not in splats
@@ -468,32 +482,22 @@ def render(self, el: ds.DocstringSectionRaises):
 
         return self._render_definition_list("Raises:", rows, title_class="highlight")
 
-    # @dispatch
-    # def render(self, el: ds.DocstringReturn) -> str:
-    #     returns = []
-    #     return_type = self.render_annotation(el.annotation)
-    #     if return_type:
-    #         returns.append(return_type)
-
-    #     return_desc = sanitize(el.description, allow_markdown=True)
-    #     if return_desc:
-    #         returns.append(return_desc)
+    @dispatch
+    def render(self, el: ds.DocstringSectionAdmonition) -> str:
+        print(f'Admonition: {el.title} {el.value.description}')
 
-    #     returns_text = " -- ".join(returns)
-    #     if returns_text:
-    #         return self._render_definition_list("Returns:", [returns_text], title_class="highlight")
-    #     else:
-    #         return ""
+        rows = []
+        if el.title.lower().startswith("note"):
+            rows.append(f'::: {{.callout-note title="{el.title}"}}')
+        elif el.title.lower().startswith("warn"):
+            rows.append(f'::: {{.callout-warning title="{el.title}"}}')
+        else:
+            rows.append(f'::: {{.callout-tip title="{el.title}"}}')
 
-    @dispatch
-    def render(self, el: ds.DocstringRaise):
-        # similar to DocstringParameter, but no name or default
-        annotation = self.render_annotation(el.annotation)
-        return f'{annotation} -- {sanitize(el.description, allow_markdown=True)}'
+        rows.append(el.value.description)
+        rows.append(':::')
 
-    @dispatch
-    def render(self, el: ds.DocstringSectionAdmonition):
-        return sanitize(el.value.description, allow_markdown=True)
+        return "\n".join(rows)
 
     # unsupported parts ----
 

python/docs/autosummary.py

@@ -217,7 +217,6 @@ def build(self, filter: str = "*"):
         self.write_doc_pages(pages, filter, hierarchy)
 
         # inventory ----
-        print(hierarchy)
 
         # update paths in items
         for item in items:
@@ -243,9 +242,6 @@ def build(self, filter: str = "*"):
             if location:
                 item.uri = f'{self.dir}/{location}/{path}#{fragment}'
 
-        for i in range(10):
-            print(f'Item: {items[i]}')
-
         _log.info("Creating inventory file")
         inv = self.create_inventory(items)
         if self._fast_inventory:

python/pysrc/kaskada/_timestream.py

@@ -996,8 +996,8 @@ def round(self) -> Timestream:
 
         Returns:
             A Timestream of the same type as `self`. The result contains `null`
-            if the value was `null` at that point. Otherwise, it contains
-            the result of rounding the value to the nearest integer.
+                if the value was `null` at that point. Otherwise, it contains
+                the result of rounding the value to the nearest integer.
 
         Notes:
             This method may be applied to any numeric type. For anything other
@@ -1026,9 +1026,9 @@ def greatest(self, rhs: Arg) -> Timestream:
 
         Returns:
             Each point contains the value from `self` if `self`
-            is greater than `rhs`, otherwise it contains `rhs`.
-            If any input is `null` or `NaN`, then that will be
-            the result.
+                is greater than `rhs`, otherwise it contains `rhs`.
+                If any input is `null` or `NaN`, then that will be
+                the result.
 
         See Also:
             This returns the greatest of two values. See
@@ -1045,9 +1045,9 @@ def least(self, rhs: Arg) -> Timestream:
 
         Returns:
             Each point contains the value from `self` if `self`
-            is less than `rhs`, otherwise it contains `rhs`.
-            If any input is `null` or `NaN`, then that will be
-            the result.
+                is less than `rhs`, otherwise it contains `rhs`.
+                If any input is `null` or `NaN`, then that will be
+                the result.
 
         See Also:
             This returns the least of two values. See
@@ -1110,8 +1110,8 @@ def write(
 
         Returns:
             An `ExecutionProgress` which allows iterating (synchronously or asynchronously)
-            over the progress information, as well as cancelling the query if it is no longer
-            needed.
+                over the progress information, as well as cancelling the query if it is no longer
+                needed.
         """
         raise NotImplementedError
 
@@ -1178,7 +1178,7 @@ def run_iter(
 
         Returns:
             Iterator over data of the corresponding kind. The `QueryIterator` allows
-            cancelling the query or materialization as well as iterating.
+                cancelling the query or materialization as well as iterating.
 
         See Also:
             - [](`~kaskada.Timestream.write`): To write the results directly to a
@@ -1217,7 +1217,7 @@ def explain(
 
         Returns:
             A GraphViz representation of the execution plan as a string, SVG string, or SVG.
-            Specific representation depends on the `format` argument.
+                Specific representation depends on the `format` argument.
 
         Raises:
             ValueError: if the `kind` is not recognized or the `format` is not supported.