feat: add Auto signature_path and member_options fields

Author: machow

quartodoc/builder/blueprint.py

@@ -116,15 +116,10 @@ def _to_simple_dict(el: "BaseModel"):
     return json.loads(el.json(exclude_unset=True))
 
 
-def _non_default_entries(el: "BaseModel"):
-    field_defaults = {mf.name: mf.default for mf in el.__fields__.values()}
-    set_fields = [
-        k for k, v in el if field_defaults[k] is not v if not isinstance(v, MISSING)
-    ]
-
+def _non_default_entries(el: Auto):
     d = el.dict()
 
-    return {k: d[k] for k in set_fields}
+    return {k: d[k] for k in el._fields_specified}
 
 
 class BlueprintTransformer(PydanticTransformer):
@@ -280,6 +275,12 @@ def enter(self, el: Auto):
 
         # Three cases for structuring child methods ----
 
+        _defaults = {"dynamic": dynamic, "package": path}
+        if el.member_options is not None:
+            member_options = {**_defaults, **_non_default_entries(el.member_options)}
+        else:
+            member_options = _defaults
+
         children = []
         for entry in raw_members:
             # Note that we could have iterated over obj.members, but currently
@@ -293,7 +294,7 @@ def enter(self, el: Auto):
             # create Doc element for member ----
             # TODO: when a member is a Class, it is currently created using
             # defaults, and there is no way to override those.
-            doc = self.visit(Auto(name=relative_path, dynamic=dynamic, package=path))
+            doc = self.visit(Auto(name=relative_path, **member_options))
 
             # do no document submodules
             if (
@@ -325,7 +326,9 @@ def enter(self, el: Auto):
             children.append(res)
 
         is_flat = el.children == ChoicesChildren.flat
-        return Doc.from_griffe(el.name, obj, members=children, flat=is_flat)
+        return Doc.from_griffe(
+            el.name, obj, children, flat=is_flat, signature_path=el.signature_path
+        )
 
     @staticmethod
     def _fetch_members(el: Auto, obj: dc.Object | dc.Alias):

quartodoc/layout.py

@@ -4,7 +4,7 @@
 import logging
 
 from enum import Enum
-from pydantic import BaseModel, Field, Extra
+from pydantic import BaseModel, Field, Extra, PrivateAttr
 
 from typing_extensions import Annotated
 from typing import Literal, Union, Optional
@@ -201,9 +201,13 @@ class ChoicesChildren(Enum):
     linked = "linked"
 
 
+SignatureOptions = Literal["full", "short", "relative"]
+
+
 class AutoOptions(_Base):
     """Options available for Auto content layout element."""
 
+    signature_path: SignatureOptions = "relative"
     members: Optional[list[str]] = None
     include_private: bool = False
     include_imports: bool = False
@@ -221,6 +225,15 @@ class AutoOptions(_Base):
     dynamic: Union[None, bool, str] = None
     children: ChoicesChildren = ChoicesChildren.embedded
     package: Union[str, None, MISSING] = MISSING()
+    member_options: Optional["AutoOptions"] = None
+
+    # for tracking fields users manually specify
+    # so we can tell them apart from defaults
+    _fields_specified: list[str] = PrivateAttr(default=())
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._fields_specified = tuple(kwargs)
 
 
 class Auto(AutoOptions):
@@ -259,6 +272,8 @@ class Auto(AutoOptions):
         Style for presenting members. Either separate, embedded, or flat.
     package:
         If specified, object lookup will be relative to this path.
+    member_options:
+        Options to apply to members. These can include any of the options above.
 
 
     """
@@ -320,6 +335,7 @@ class Doc(_Docable):
     name: str
     obj: Union[dc.Object, dc.Alias]
     anchor: str
+    signature_path: SignatureOptions = "relative"
 
     class Config:
         arbitrary_types_allowed = True
@@ -333,14 +349,20 @@ def from_griffe(
         members=None,
         anchor: str = None,
         flat: bool = False,
+        signature_path: str = "relative",
     ):
         if members is None:
             members = []
 
         kind = obj.kind.value
         anchor = obj.path if anchor is None else anchor
 
-        kwargs = {"name": name, "obj": obj, "anchor": anchor}
+        kwargs = {
+            "name": name,
+            "obj": obj,
+            "anchor": anchor,
+            "signature_path": signature_path,
+        }
 
         if kind == "function":
             return DocFunction(**kwargs)
@@ -431,6 +453,7 @@ class Config:
 Layout.update_forward_refs()
 Section.update_forward_refs()
 Page.update_forward_refs()
+AutoOptions.update_forward_refs()
 Auto.update_forward_refs()
 MemberPage.update_forward_refs()
 Interlaced.update_forward_refs()

quartodoc/renderers/md_renderer.py

@@ -3,6 +3,7 @@
 import quartodoc.ast as qast
 
 from contextlib import contextmanager
+from functools import wraps
 from griffe.docstrings import dataclasses as ds
 from griffe import dataclasses as dc
 from tabulate import tabulate
@@ -27,6 +28,29 @@ def _has_attr_section(el: dc.Docstring | None):
     return any([isinstance(x, ds.DocstringSectionAttributes) for x in el.parsed])
 
 
+def with_doc_options(f):
+    """Decorator to add docstring options to a renderer.
+    
+    Currently, the renderer renders signatures directly from griffe objects,
+    so this decorator is used, to temporarily set some things from layout.Doc
+    as renderer settings.
+
+    (Not ideal but works for now.)
+    """
+
+    @wraps(f)
+    def wrapper(self, el, *args, **kwargs):
+        orig = self.display_name
+        self.display_name = el.signature_path
+        res = f(self, el, *args, **kwargs)
+
+        self.display_name = orig
+
+        return res
+    
+    return wrapper
+
+
 class MdRenderer(Renderer):
     """Render docstrings to markdown.
 
@@ -86,7 +110,7 @@ def _increment_header(self, n=1):
 
     def _fetch_object_dispname(self, el: "dc.Alias | dc.Object"):
         # TODO: copied from Builder, should move into util function
-        if self.display_name == "name":
+        if self.display_name in {"name", "short"}:
             return el.name
         elif self.display_name == "relative":
             return ".".join(el.path.split(".")[1:])
@@ -246,6 +270,7 @@ def render(self, el: layout.Doc):
         raise NotImplementedError(f"Unsupported Doc type: {type(el)}")
 
     @dispatch
+    @with_doc_options
     def render(self, el: Union[layout.DocClass, layout.DocModule]):
         title = self.render_header(el)
 
@@ -314,12 +339,14 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]):
         return "\n\n".join([title, body, *attr_docs, *class_docs, *meth_docs])
 
     @dispatch
+    @with_doc_options
     def render(self, el: layout.DocFunction):
         title = self.render_header(el)
 
         return "\n\n".join([title, self.render(el.obj)])
 
     @dispatch
+    @with_doc_options
     def render(self, el: layout.DocAttribute):
         title = self.render_header(el)
         return "\n\n".join([title, self.render(el.obj)])

quartodoc/tests/__snapshots__/test_renderers.ambr

@@ -232,6 +232,15 @@
   A function
   '''
 # ---
+# name: test_render_doc_signature_path
+  '''
+  # example.a_func { #quartodoc.tests.example.a_func }
+  
+  `a_func()`
+  
+  A function
+  '''
+# ---
 # name: test_render_docstring_numpy_linebreaks
   '''
   # f_numpy_with_linebreaks { #quartodoc.tests.example_docstring_styles.f_numpy_with_linebreaks }

quartodoc/tests/test_builder_blueprint.py

@@ -87,7 +87,7 @@ def test_blueprint_default_dynamic(bp):
     assert NOTE in res.obj.docstring.value
 
 
-def test_blueprint_auto_package(bp):
+def test_blueprint_auto_anchor(bp):
     auto = lo.Auto(name="a_func", package="quartodoc.tests.example")
     res = bp.visit(auto)
 
@@ -183,3 +183,19 @@ def test_blueprint_fetch_members_include_inherited():
 
     member_names = set([entry.name for entry in bp.members])
     assert "some_method" in member_names
+
+
+def test_blueprint_member_options():
+    auto = lo.Auto(
+        name="quartodoc.tests.example",
+        member_options={"signature_path": "short"},
+        members=["AClass"],
+    )
+    bp = blueprint(auto)
+    doc_a_class = bp.members[0]
+
+    # member has option set
+    assert doc_a_class.signature_path == "short"
+
+    # this currently does not apply to members of members
+    assert doc_a_class.members[0].signature_path == "relative"

quartodoc/tests/test_renderers.py

@@ -145,3 +145,13 @@ def test_render_docstring_numpy_linebreaks(snapshot, renderer):
     res = renderer.render(bp)
 
     assert res == snapshot
+
+
+def test_render_doc_signature_path(snapshot, renderer):
+    package = "quartodoc.tests"
+    auto = Auto(name="example.a_func", package=package, signature_path="short")
+    bp = blueprint(auto)
+
+    res = renderer.render(bp)
+
+    assert res == snapshot