Merge pull request #81 from machow/feat-module-doc

Feat module doc

Author: machow

quartodoc/ast.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import warnings
+
 from enum import Enum
 from dataclasses import dataclass
 from griffe.docstrings import dataclasses as ds
@@ -179,7 +181,15 @@ def fields(el: dc.Object):
 
 @dispatch
 def fields(el: dc.ObjectAliasMixin):
-    return fields(el.target)
+    try:
+        return fields(el.target)
+    except dc.AliasResolutionError:
+        warnings.warn(
+            f"Could not resolve Alias target `{el.target_path}`."
+            " This often occurs because the module was not loaded (e.g. it is a"
+            " package outside of your package)."
+        )
+        return ["name", "target_path"]
 
 
 @dispatch

quartodoc/autosummary.py

@@ -199,8 +199,8 @@ def replace_docstring(obj: dc.Object | dc.Alias, f=None):
     # since griffe reads class docstrings from the .__init__ method, this should
     # also have the effect of updating the class docstring.
     if isinstance(obj, dc.Class):
-        for func_obj in obj.functions.values():
-            replace_docstring(func_obj)
+        for child_obj in obj.members.values():
+            replace_docstring(child_obj)
 
     if f is None:
         mod = importlib.import_module(obj.module.canonical_path)
@@ -253,12 +253,14 @@ def dynamic_alias(
     except ValueError:
         mod_name, object_path = path, None
 
+    # get underlying object dynamically ----
+
     mod = importlib.import_module(mod_name)
 
     # Case 1: path is just to a module
     if object_path is None:
-        attr = get_object(path)
-        canonical_path = attr.__name__
+        attr = mod
+        canonical_path = mod.__name__
 
     # Case 2: path is to a member of a module
     else:
@@ -284,7 +286,7 @@ def dynamic_alias(
 
         attr = crnt_part
 
-    # start loading things with griffe ----
+    # start loading object with griffe ----
 
     if target:
         obj = get_object(target, loader=loader)

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/builder/collect.py

@@ -38,8 +38,7 @@ def exit(self, el: layout.Doc):
         page_node = self.find_page_node()
         p_el = page_node.value
 
-        anchor = el.name
-        uri = f"{self.base_dir}/{p_el.path}.html#{anchor}"
+        uri = f"{self.base_dir}/{p_el.path}.html#{el.anchor}"
         self.items.append(
             layout.Item(name=el.obj.path, obj=el.obj, uri=uri, dispname=None)
         )

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
@@ -180,7 +206,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 +226,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 +240,7 @@ class DocFunction(Doc):
 class DocClass(Doc):
     kind: Literal["class"] = "class"
     members: list[Union[MemberPage, Doc, Link]] = tuple()
+    flat: bool
 
 
 class DocAttribute(Doc):
@@ -218,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 ----
 
 
@@ -248,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)
@@ -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):

quartodoc/tests/example_dynamic.py

@@ -1,3 +1,5 @@
+from functools import partial
+
 NOTE = "Notes\n----\nI am a note"
 
 
@@ -9,3 +11,18 @@ def f(a, b, c):
 
 
 f.__doc__ = f.__doc__.format(note=NOTE)
+
+
+class AClass:
+    def simple(self, x):
+        """A simple method"""
+
+    def dynamic_doc(self, x):
+        ...
+
+    dynamic_doc.__doc__ = """A dynamic method"""
+
+    # note that we could use the partialmethod, but I am not sure how to
+    # correctly set its __doc__ attribute in that case.
+    dynamic_create = partial(dynamic_doc, x=1)
+    dynamic_create.__doc__ = dynamic_doc.__doc__

quartodoc/tests/test_ast.py

@@ -75,6 +75,17 @@ def test_preview_no_fail(capsys):
     assert "get_object" in res.out
 
 
+def test_preview_warn_alias_no_load():
+    # fetch an alias to pydantic.BaseModel, without loading pydantic
+    # attempting to get alias.target will fail, but preview should still work.
+    obj = get_object("quartodoc.ast.BaseModel", load_aliases=False)
+    with pytest.warns(UserWarning) as record:
+        qast.preview(obj)
+
+    msg = record[0].message.args[0]
+    assert "Could not resolve Alias target `pydantic.BaseModel`" in msg
+
+
 @pytest.mark.parametrize(
     "text, dst",
     [("One\n---\nab\n\nTwo\n---\n\ncd", [("One", "ab\n\n"), ("Two", "\ncd")])],