Merge pull request #257 from machow/feat-member-signature

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,13 @@ 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_name=el.signature_name,
+        )
 
     @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_name: 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_name: SignatureOptions = "relative"
 
     class Config:
         arbitrary_types_allowed = True
@@ -333,14 +349,20 @@ def from_griffe(
         members=None,
         anchor: str = None,
         flat: bool = False,
+        signature_name: 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_name": signature_name,
+        }
 
         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
@@ -86,7 +87,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:])
@@ -128,6 +129,22 @@ def render_annotation(self, el: "str | expr.Name | expr.Expression | None"):
 
     # signature method --------------------------------------------------------
 
+    @dispatch
+    def signature(self, el: layout.Doc):
+        orig = self.display_name
+
+        # set signature path, generate signature, then set back
+        # TODO: this is for backwards compatibility with the old approach
+        # of only defining signature over griffe objects, which projects
+        # like shiny currently extend
+        self.display_name = el.signature_name
+        res = self.signature(el.obj)
+        self.display_name = orig
+
+        return res
+
+
+
     @dispatch
     def signature(self, el: dc.Alias, source: Optional[dc.Alias] = None):
         """Return a string representation of an object's signature."""
@@ -310,28 +327,30 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]):
                         [self.render(x) for x in raw_meths if isinstance(x, layout.Doc)]
                     )
 
+
+        str_sig = self.signature(el)
+        sig_part = [str_sig] if self.show_signature else []
+
         body = self.render(el.obj)
-        return "\n\n".join([title, body, *attr_docs, *class_docs, *meth_docs])
 
-    @dispatch
-    def render(self, el: layout.DocFunction):
-        title = self.render_header(el)
 
-        return "\n\n".join([title, self.render(el.obj)])
+        return "\n\n".join([title, *sig_part, body, *attr_docs, *class_docs, *meth_docs])
 
     @dispatch
-    def render(self, el: layout.DocAttribute):
+    def render(self, el: Union[layout.DocFunction, layout.DocAttribute]):
         title = self.render_header(el)
-        return "\n\n".join([title, self.render(el.obj)])
+
+        str_sig = self.signature(el)
+        sig_part = [str_sig] if self.show_signature else []
+
+        return "\n\n".join([title, *sig_part, self.render(el.obj)])
 
     # render griffe objects ===================================================
 
     @dispatch
     def render(self, el: Union[dc.Object, dc.Alias]):
         """Render high level objects representing functions, classes, etc.."""
 
-        str_sig = self.signature(el)
-
         str_body = []
         if el.docstring is None:
             pass
@@ -347,10 +366,7 @@ def render(self, el: Union[dc.Object, dc.Alias]):
                 else:
                     str_body.append(body)
 
-        if self.show_signature:
-            parts = [str_sig, *str_body]
-        else:
-            parts = [*str_body]
+        parts = [*str_body]
 
         return "\n\n".join(parts)
 

quartodoc/tests/__snapshots__/test_renderers.ambr

@@ -232,6 +232,15 @@
   A function
   '''
 # ---
+# name: test_render_doc_signature_name
+  '''
+  # 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_basic.py

@@ -49,10 +49,7 @@ def test_render_attribute():
     # TODO: snapshot tests
     a = get_object("quartodoc", "tests.example_attribute.a")
 
-    assert (
-        MdRenderer().render(a)
-        == "`tests.example_attribute.a`\n\nI am an attribute docstring"
-    )
+    assert MdRenderer().render(a) == "I am an attribute docstring"
 
 
 def test_get_object_dynamic_module_root():

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_name": "short"},
+        members=["AClass"],
+    )
+    bp = blueprint(auto)
+    doc_a_class = bp.members[0]
+
+    # member has option set
+    assert doc_a_class.signature_name == "short"
+
+    # this currently does not apply to members of members
+    assert doc_a_class.members[0].signature_name == "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_name(snapshot, renderer):
+    package = "quartodoc.tests"
+    auto = Auto(name="example.a_func", package=package, signature_name="short")
+    bp = blueprint(auto)
+
+    res = renderer.render(bp)
+
+    assert res == snapshot