feat: support Interlaced doc layouts

Author: machow

quartodoc/layout.py

@@ -60,7 +60,7 @@ class Section(_Base):
     title: str
     desc: str
     package: Union[str, None, MISSING] = MISSING()
-    contents: list[Union[ContentElement, Doc, _AutoDefault]]
+    contents: ContentList
 
 
 class SummaryDetails(_Base):
@@ -79,7 +79,7 @@ class Page(_Base):
     summary: Optional[SummaryDetails] = None
     flatten: bool = False
 
-    contents: list[Union[ContentElement, Doc, _AutoDefault]]
+    contents: ContentList
 
     @property
     def obj(self):
@@ -99,6 +99,32 @@ class MemberPage(Page):
     contents: list[Doc]
 
 
+class Interlaced(BaseModel):
+    """A group of objects, whose documentation will be interlaced.
+
+    Rather than list each object's documentation in sequence, this element indicates
+    that each piece of documentation (e.g. signatures, examples) should be grouped
+    together.
+    """
+
+    kind: Literal["interlaced"] = "interlaced"
+    package: Union[str, None, MISSING] = MISSING()
+
+    # note that this is similar to a ContentList, except it cannot include
+    # elements like Pages, etc..
+    contents: list[Union[Auto, Doc, _AutoDefault]]
+
+    @property
+    def name(self):
+        if not self.contents:
+            raise AttributeError(
+                f"Cannot get property name for object of type {type(self)}."
+                " There are no content elements."
+            )
+
+        return self.contents[0].name
+
+
 class Text(_Base):
     kind: Literal["text"] = "text"
     contents: str
@@ -224,16 +250,19 @@ class DocAttribute(Doc):
 class DocModule(Doc):
     kind: Literal["module"] = "module"
     members: list[Union[MemberPage, Doc, Link]] = tuple()
+    flat: bool
 
 
 SectionElement = Annotated[Union[Section, Page], Field(discriminator="kind")]
 """Entry in the sections list."""
 
 ContentElement = Annotated[
-    Union[Page, Section, Text, Auto], Field(discriminator="kind")
+    Union[Page, Section, Interlaced, Text, Auto], Field(discriminator="kind")
 ]
 """Entry in the contents list."""
 
+ContentList = list[Union[ContentElement, Doc, _AutoDefault]]
+
 # Item ----
 
 
@@ -254,3 +283,4 @@ class Config:
 Page.update_forward_refs()
 Auto.update_forward_refs()
 MemberPage.update_forward_refs()
+Interlaced.update_forward_refs()

quartodoc/renderers/md_renderer.py

@@ -181,6 +181,53 @@ def render(self, el: layout.Section):
             body = list(map(self.render, el.contents))
 
         return "\n\n".join([section_top, *body])
+    
+    @dispatch
+    def render(self, el: layout.Interlaced):
+        # render a sequence of objects with like-sections together.
+        # restrict its behavior to documenting functions for now ----
+        for doc in el.contents:
+            if not isinstance(doc, (layout.DocFunction, layout.DocAttribute)):
+                raise NotImplementedError(
+                    "Can only render Interlaced elements if all content elements"
+                    " are function or attribute docs."
+                    f" Found an element of type {type(doc)}, with name {doc.name}"
+                )
+
+        # render ----
+        # currently, we use everything from the first function, and just render
+        # the signatures together
+        first_doc = el.contents[0]
+        objs = [doc.obj for doc in el.contents]
+
+        if first_doc.obj.docstring is None:
+            raise ValueError("The first element of Interlaced must have a docstring.")
+
+        
+        str_title = self.render_header(first_doc)
+        str_sig = "\n\n".join(map(self.signature, objs))
+        str_body = []
+
+        # TODO: we should also interlace parameters and examples
+        # parsed = map(qast.transform, [x.docstring.parsed for x in objs if x.docstring])
+
+        # TODO: this is copied from the render method for dc.Object
+        for section in qast.transform(first_doc.obj.docstring.parsed):
+            title = section.title or section.kind.value
+            body = self.render(section)
+
+            if title != "text":
+                header = f"{'#' * (self.crnt_header_level + 1)} {title.title()}"
+                str_body.append("\n\n".join([header, body]))
+            else:
+                str_body.append(body)
+
+        if self.show_signature:
+            parts = [str_title, str_sig, *str_body]
+        else:
+            parts = [str_title, *str_body]
+
+        return "\n\n".join(parts)
 
     @dispatch
     def render(self, el: layout.Doc):
@@ -226,7 +273,8 @@ def render(self, el: Union[layout.DocClass, layout.DocModule]):
                 extra_parts.append(meths)
 
                 # TODO use context manager, or context variable?
-                with self._increment_header(2):
+                n_incr = 1 if el.flat else 2
+                with self._increment_header(n_incr):
                     meth_docs = [self.render(x) for x in raw_meths if isinstance(x, layout.Doc)]
 
         body = self.render(el.obj)
@@ -311,7 +359,7 @@ def render(self, el: dc.Parameter):
         elif has_default:
             res = f"{glob}{el.name}={el.default}"
         else:
-            res = el.name
+            res = f"{glob}{el.name}"
 
         return sanitize(res)
 
@@ -477,6 +525,12 @@ def summarize(self, el: layout.Page):
     def summarize(self, el: layout.MemberPage):
         # TODO: model should validate these only have a single entry
         return self.summarize(el.contents[0], el.path, shorten = True)
+    
+    @dispatch
+    def summarize(self, el: layout.Interlaced, *args, **kwargs):
+        rows = [self.summarize(doc, *args, **kwargs) for doc in el.contents]
+
+        return "\n".join(rows)
 
     @dispatch
     def summarize(self, el: layout.Doc, path: Optional[str] = None, shorten: bool = False):