fix: blueprint correct member path, handles flat children option

Author: machow

quartodoc/builder/blueprint.py

@@ -44,6 +44,13 @@ def __init__(self, get_object=None, parser="numpy"):
 
         self.crnt_package = None
 
+    @staticmethod
+    def _append_member_path(path: str, new: str):
+        if ":" in path:
+            return f"{path}.{new}"
+
+        return f"{path}:{new}"
+
     def get_object_fixed(self, *args, **kwargs):
         try:
             return self.get_object(*args, **kwargs)
@@ -79,7 +86,7 @@ def exit(self, el: Section):
         # otherwise, replace all contents with pages.
         new = el.copy()
         contents = [
-            Page(contents=[el], path=el.name) if isinstance(el, Doc) else el
+            Page(contents=[el], path=el.name) if not isinstance(el, Page) else el
             for el in new.contents
         ]
 
@@ -112,7 +119,8 @@ def enter(self, el: Auto):
             # but the actual objects on the target.
             # On the other hand, we've wired get_object up to make sure getting
             # the member of an Alias also returns an Alias.
-            obj_member = self.get_object_fixed(f"{path}.{entry}", dynamic=el.dynamic)
+            member_path = self._append_member_path(path, entry)
+            obj_member = self.get_object_fixed(member_path, dynamic=el.dynamic)
 
             # do no document submodules
             if obj_member.kind.value == "module":
@@ -126,7 +134,7 @@ def enter(self, el: Auto):
                 res = MemberPage(path=obj_member.path, contents=[doc])
             # Case2: use just the Doc element, so it gets embedded directly
             # into the class being documented
-            elif el.children == ChoicesChildren.embedded:
+            elif el.children in {ChoicesChildren.embedded, ChoicesChildren.flat}:
                 res = doc
             # Case 3: make each member just a link in a summary table.
             # if the page for the member is not created somewhere else, then it
@@ -139,7 +147,8 @@ def enter(self, el: Auto):
 
             children.append(res)
 
-        return Doc.from_griffe(el.name, obj, members=children)
+        is_flat = el.children == ChoicesChildren.flat
+        return Doc.from_griffe(el.name, obj, members=children, flat=is_flat)
 
     @staticmethod
     def _fetch_members(el: Auto, obj: dc.Object | dc.Alias):
@@ -182,6 +191,17 @@ def exit(self, el: Page):
         return el
 
 
+def blueprint(el: _Base, package: str = None):
+    """Create a blueprint of a layout element, that is ready to render."""
+
+    trans = BlueprintTransformer()
+
+    if package is not None:
+        trans.crnt_package = package
+
+    return trans.visit(el)
+
+
 def strip_package_name(el: _Base, package: str):
     """Removes leading package name from layout Pages."""
 

quartodoc/layout.py

@@ -180,7 +180,12 @@ class Config:
 
     @classmethod
     def from_griffe(
-        cls, name, obj: Union[dc.Object, dc.Alias], members=None, anchor: str = None
+        cls,
+        name,
+        obj: Union[dc.Object, dc.Alias],
+        members=None,
+        anchor: str = None,
+        flat: bool = False,
     ):
         if members is None:
             members = []
@@ -195,9 +200,9 @@ def from_griffe(
         elif kind == "attribute":
             return DocAttribute(**kwargs)
         elif kind == "class":
-            return DocClass(members=members, **kwargs)
+            return DocClass(members=members, flat=flat, **kwargs)
         elif kind == "module":
-            return DocModule(members=members, **kwargs)
+            return DocModule(members=members, flat=flat, **kwargs)
 
         raise TypeError(f"Cannot handle auto for object kind: {obj.kind}")
 
@@ -209,6 +214,7 @@ class DocFunction(Doc):
 class DocClass(Doc):
     kind: Literal["class"] = "class"
     members: list[Union[MemberPage, Doc, Link]] = tuple()
+    flat: bool
 
 
 class DocAttribute(Doc):

quartodoc/tests/test_builder.py

@@ -0,0 +1,72 @@
+from quartodoc import get_object
+from quartodoc import layout as lo
+from quartodoc.builder.blueprint import BlueprintTransformer
+import pytest
+
+TEST_MOD = "quartodoc.tests.example"
+
+
+@pytest.fixture
+def lay():
+    return lo.Layout(
+        sections=[
+            lo.Section(
+                title="",
+                desc="",
+                contents=[f"{TEST_MOD}.a_func", f"{TEST_MOD}.a_attr"],
+            ),
+            lo.Section(
+                title="",
+                desc="",
+                contents=[
+                    f"{TEST_MOD}.AClass",
+                    f"{TEST_MOD}.AClass.a_attr",
+                    f"{TEST_MOD}.AClass.a_method",
+                ],
+            ),
+        ]
+    )
+
+
+@pytest.fixture
+def bp():
+    return BlueprintTransformer()
+
+
+@pytest.mark.parametrize("path", ["quartodoc.get_object", "quartodoc:get_object"])
+def test_blueprint_basic(bp, path):
+    auto = lo.Auto(name=path)
+    res = bp.visit(auto)
+
+    obj = get_object(path)
+    dst = lo.DocFunction(
+        name=path, obj=obj, anchor="quartodoc.get_object", kind="function"
+    )
+
+    # TODO: it's hard to compare pydantic models with griffe objects in them
+    # we likely need to define how to serialize them to json.
+    assert str(res) == str(dst)
+
+
+@pytest.mark.parametrize("dynamic", [False, True])
+def test_blueprint_visit_class(bp, dynamic):
+    path = "quartodoc.tests.example:AClass"
+    auto = lo.Auto(name=path, members=["a_method"], dynamic=dynamic)
+    res = bp.visit(auto)
+
+    assert isinstance(res, lo.DocClass)
+    assert len(res.members) == 1
+    assert res.members[0].name == "a_method"
+    assert res.members[0].obj.path == path.replace(":", ".") + ".a_method"
+
+
+@pytest.mark.parametrize("dynamic", [False, True])
+def test_blueprint_visit_module(bp, dynamic):
+    path = "quartodoc.tests.example"
+    auto = lo.Auto(name=path, members=["a_func"], dynamic=dynamic)
+    res = bp.visit(auto)
+
+    assert isinstance(res, lo.DocModule)
+    assert len(res.members) == 1
+    assert res.members[0].name == "a_func"
+    assert res.members[0].obj.path == path.replace(":", ".") + ".a_func"