Merge pull request #326 from machow/fix-griffe-compat

fix: compatibility with griffe 0.39

Author: machow

Makefile

@@ -43,6 +43,7 @@ docs-build-readme:
 		 --output README.md \
 		 --output-dir ..
 
+docs-build: export PLUM_SIMPLE_DOC=1
 docs-build: docs-build-examples
 	cd docs && quarto add --no-prompt ..
 	cd docs && quartodoc build

quartodoc/ast.py

@@ -7,7 +7,7 @@
 from griffe.docstrings import dataclasses as ds
 from griffe import dataclasses as dc
 from plum import dispatch
-from typing import Union
+from typing import Type, Union
 
 from ._pydantic_compat import BaseModel  # for previewing
 
@@ -44,7 +44,7 @@ class DocstringSectionKindPatched(Enum):
 
 
 class _DocstringSectionPatched(ds.DocstringSection):
-    _registry: "dict[Enum, _DocstringSectionPatched]" = {}
+    _registry: "dict[str, Type[_DocstringSectionPatched]]" = {}
 
     def __init__(self, value: str, title: "str | None" = None):
         super().__init__(title)
@@ -102,18 +102,31 @@ def transform(cls, el: ds.DocstringSection) -> list[ds.DocstringSection]:
         class represents a section like See Also, etc..
         """
 
-        if not isinstance(el, ds.DocstringSectionText):
+        if not isinstance(el, (ds.DocstringSectionText, ds.DocstringSectionAdmonition)):
             return [el]
 
-        splits = cls.split_sections(el.value)
         results = []
-        for title, body in splits:
-            sub_cls = cls._registry.get(title.lower(), ds.DocstringSectionText)
 
-            # note that griffe currently doesn't store the title anywhere,
-            # but we add the exact title here, so we can be flexible about the
-            # sections we parse (e.g. Note instead of Notes) in the future.
-            results.append(sub_cls(body, title))
+        # griffe < 0.39 w/ numpydoc uses DocstringSectionText for unhandled section
+        # but later versions always use Admonitions. Note it may still use Text
+        # for areas of docstrings not associated with particular sections (e.g. freeform
+        # text betwen a parameters section and the next section).
+        if isinstance(el, ds.DocstringSectionText):
+            # handle griffe < 0.39 case
+            splits = cls.split_sections(el.value)
+            for title, body in splits:
+                sub_cls = cls._registry.get(title.lower(), ds.DocstringSectionText)
+
+                # note that griffe currently doesn't store the title anywhere,
+                # but we add the exact title here, so we can be flexible about the
+                # sections we parse (e.g. Note instead of Notes) in the future.
+                results.append(sub_cls(body, title))
+        elif isinstance(el, ds.DocstringSectionAdmonition):
+            sub_cls = cls._registry.get(el.title.lower(), None)
+            if sub_cls:
+                results.append(sub_cls(el.value.contents, el.title))
+            else:
+                results.append(el)
 
         return results or [el]
 

quartodoc/renderers/md_renderer.py

@@ -140,6 +140,7 @@ def render_annotation(self, el: expr.Expr) -> str:
 
     @dispatch
     def signature(self, el: layout.Doc):
+        """Return a string representation of an object's signature."""
         orig = self.display_name
 
         # set signature path, generate signature, then set back
@@ -156,7 +157,6 @@ def signature(self, el: layout.Doc):
 
     @dispatch
     def signature(self, el: dc.Alias, source: Optional[dc.Alias] = None):
-        """Return a string representation of an object's signature."""
         return self.signature(el.final_target, el)
 
     @dispatch
@@ -508,7 +508,7 @@ def render(self, el: ds.DocstringSectionAdmonition):
             # TODO: attempt to parse See Also sections
             return convert_rst_link_to_md(el.value.description)
 
-        raise NotImplementedError(f"Unsupported DocstringSectionAdmonition kind: {kind}")
+        return el.value.description
 
     # warnings ----
 

quartodoc/tests/__snapshots__/test_renderers.ambr

@@ -307,6 +307,10 @@
   |--------|--------|------------------|------------|
   | `a`    | int    | The a parameter. | _required_ |
   | `b`    | str    | The b parameter. | _required_ |
+  
+  ## Custom Admonition
+  
+  Some text.
   '''
 # ---
 # name: test_render_docstring_styles[numpy]
@@ -323,6 +327,10 @@
   |--------|--------|------------------|------------|
   | `a`    |        | The a parameter. | _required_ |
   | `b`    | str    | The b parameter. | _required_ |
+  
+  ## Custom Admonition
+  
+  Some text.
   '''
 # ---
 # name: test_render_docstring_styles[sphinx]

quartodoc/tests/example_docstring_styles.py

@@ -4,6 +4,9 @@ def f_google(a, b: str):
     Args:
         a (int): The a parameter.
         b: The b parameter.
+
+    Custom Admonition:
+        Some text.
     """
 
 
@@ -26,6 +29,9 @@ def f_numpy(a, b: str):
     b:
         The b parameter.
 
+    Custom Admonition
+    -----------------
+    Some text.
     """
 
 
@@ -41,5 +47,4 @@ def f_numpy_with_linebreaks(a, b: str):
 
     b:
         The b parameter.
-
     """