feat(builder): add top-level dynamic option

Author: machow

quartodoc/autosummary.py

@@ -340,6 +340,9 @@ class Builder:
         A directory where source files to be documented live. This is only necessary
         if you are not documenting a package, but collection of scripts. Use a "."
         to refer to the current directory.
+    dynamic:
+        Whether to dynamically load all python objects. By default, objects are
+        loaded using static analysis.
 
     """
 
@@ -382,6 +385,7 @@ def __init__(
         sidebar: "str | None" = None,
         rewrite_all_pages=False,
         source_dir: "str | None" = None,
+        dynamic: bool | None = None,
     ):
         self.layout = self.load_layout(sections=sections, package=package)
 
@@ -398,6 +402,7 @@ def __init__(
 
         self.rewrite_all_pages = rewrite_all_pages
         self.source_dir = str(Path(source_dir).absolute()) if source_dir else None
+        self.dynamic = dynamic
 
     def load_layout(self, sections: dict, package: str):
         # TODO: currently returning the list of sections, to make work with
@@ -428,7 +433,7 @@ def build(self, filter: str = "*"):
         # shaping and collection ----
 
         _log.info("Generating blueprint.")
-        blueprint = blueprint(self.layout)
+        blueprint = blueprint(self.layout, self.dynamic)
 
         _log.info("Collecting pages and inventory items.")
         pages, items = collect(blueprint, base_dir=self.dir)

quartodoc/builder/blueprint.py

@@ -45,6 +45,7 @@ def __init__(self, get_object=None, parser="numpy"):
             self.get_object = get_object
 
         self.crnt_package = None
+        self.dynamic = None
 
     @staticmethod
     def _append_member_path(path: str, new: str):
@@ -109,7 +110,9 @@ def enter(self, el: Auto):
 
         _log.info(f"Getting object for {path}")
 
-        obj = self.get_object_fixed(path, dynamic=el.dynamic)
+        dynamic = el.dynamic if el.dynamic is not None else self.dynamic
+
+        obj = self.get_object_fixed(path, dynamic=dynamic)
         raw_members = self._fetch_members(el, obj)
 
         # Three cases for structuring child methods ----
@@ -122,7 +125,7 @@ def enter(self, el: Auto):
             # On the other hand, we've wired get_object up to make sure getting
             # the member of an Alias also returns an Alias.
             member_path = self._append_member_path(path, entry)
-            obj_member = self.get_object_fixed(member_path, dynamic=el.dynamic)
+            obj_member = self.get_object_fixed(member_path, dynamic=dynamic)
 
             # do no document submodules
             if obj_member.kind.value == "module":
@@ -198,7 +201,7 @@ def blueprint(el: Auto, package: str) -> Doc:
     ...
 
 
-def blueprint(el: _Base, package: str = None) -> _Base:
+def blueprint(el: _Base, package: str = None, dynamic: None | bool = None) -> _Base:
     """Convert a configuration element to something that is ready to render.
 
     Parameters
@@ -207,6 +210,8 @@ def blueprint(el: _Base, package: str = None) -> _Base:
         An element, like layout.Auto, to transform.
     package:
         A base package name. If specified, this is prepended to the names of any objects.
+    dynamic:
+        Whether to dynamically load objects. Defaults to using static analysis.
 
     Examples
     --------
@@ -226,6 +231,9 @@ def blueprint(el: _Base, package: str = None) -> _Base:
     if package is not None:
         trans.crnt_package = package
 
+    if dynamic is not None:
+        trans.dynamic = dynamic
+
     return trans.visit(el)
 
 

quartodoc/layout.py

@@ -212,7 +212,7 @@ class Auto(_Base):
     include_private: bool = False
     include: Optional[str] = None
     exclude: Optional[str] = None
-    dynamic: Union[bool, str] = False
+    dynamic: Union[None, bool, str] = None
     children: ChoicesChildren = ChoicesChildren.embedded
 
 

quartodoc/tests/test_builder_blueprint.py

@@ -1,6 +1,6 @@
 from quartodoc import get_object
 from quartodoc import layout as lo
-from quartodoc.builder.blueprint import BlueprintTransformer
+from quartodoc.builder.blueprint import BlueprintTransformer, blueprint
 import pytest
 
 TEST_MOD = "quartodoc.tests.example"
@@ -70,3 +70,14 @@ def test_blueprint_visit_module(bp, dynamic):
     assert len(res.members) == 1
     assert res.members[0].name == "a_func"
     assert res.members[0].obj.path == path.replace(":", ".") + ".a_func"
+
+
+def test_blueprint_default_dynamic(bp):
+    from quartodoc.tests.example_dynamic import NOTE
+
+    path = "quartodoc.tests.example_dynamic:f"
+    auto = lo.Auto(name=path)
+
+    res = blueprint(auto, dynamic=True)
+    assert isinstance(res, lo.DocFunction)
+    assert NOTE in res.obj.docstring.value