feat: add options config to Section in layout

Author: machow

docs/_quarto.yml

@@ -93,19 +93,16 @@ quartodoc:
     - title: Docstring Renderers
       desc: |
         Renderers convert parsed docstrings into a target format, like markdown.
+      options:
+        dynamic: true
       contents:
         - name: MdRenderer
           children: linked
-        - name: MdRenderer.render
-          dynamic: true
-        - name: MdRenderer.render_annotation
-          dynamic: true
-        - name: MdRenderer.render_header
-          dynamic: true
-        - name: MdRenderer.signature
-          dynamic: true
-        - name: MdRenderer.summarize
-          dynamic: true
+        - MdRenderer.render
+        - MdRenderer.render_annotation
+        - MdRenderer.render_header
+        - MdRenderer.signature
+        - MdRenderer.summarize
 
     - title: API Builders
       desc: |

quartodoc/builder/blueprint.py

@@ -107,7 +107,8 @@ def __init__(self, get_object=None, parser="numpy"):
             self.get_object = get_object
 
         self.crnt_package = None
-        self.dynamic = None
+        self.options = None
+        self.dynamic = False
 
     @staticmethod
     def _append_member_path(path: str, new: str):
@@ -138,16 +139,26 @@ def visit(self, el):
         # TODO: use a context handler
         self._log("VISITING", el)
 
+        # set package ----
         package = getattr(el, "package", MISSING())
         old = self.crnt_package
 
         if not isinstance(package, MISSING):
             self.crnt_package = package
 
+        # set options ----
+        # TODO: check for Section instead?
+        options = getattr(el, "options", None)
+        old_options = self.options
+
+        if options is not None:
+            self.options = options
+
         try:
             return super().visit(el)
         finally:
             self.crnt_package = old
+            self.options = old_options
 
     @dispatch
     def enter(self, el: Layout):
@@ -208,6 +219,7 @@ def exit(self, el: Section):
     def enter(self, el: Auto):
         self._log("Entering", el)
 
+        # settings based on parent context options (package, options) ----
         # TODO: make this less brittle
         pkg = self.crnt_package
         if pkg is None:
@@ -217,6 +229,12 @@ def enter(self, el: Auto):
         else:
             path = f"{pkg}:{el.name}"
 
+        # auto default overrides
+        if self.options is not None:
+            # TODO: is this round-tripping guaranteed by pydantic?
+            el = el.__class__(**{**self.options.dict(), **el.dict()})
+
+        # fetching object ----
         _log.info(f"Getting object for {path}")
 
         dynamic = el.dynamic if el.dynamic is not None else self.dynamic

quartodoc/layout.py

@@ -78,6 +78,7 @@ class Section(_Structural):
     desc: Optional[str] = None
     package: Union[str, None, MISSING] = MISSING()
     contents: ContentList = []
+    options: Optional["AutoOptions"] = None
 
     def __init__(self, **data):
         super().__init__(**data)
@@ -199,7 +200,21 @@ class ChoicesChildren(Enum):
     linked = "linked"
 
 
-class Auto(_Base):
+class AutoOptions(_Base):
+    """Options available for Auto content layout element."""
+
+    members: Optional[list[str]] = None
+    include_private: bool = False
+    include_imports: bool = False
+    include_empty: bool = False
+    include: Optional[str] = None
+    exclude: Optional[str] = None
+    dynamic: Union[None, bool, str] = None
+    children: ChoicesChildren = ChoicesChildren.embedded
+    package: Union[str, None, MISSING] = MISSING()
+
+
+class Auto(AutoOptions):
     """Configure a python object to document (e.g. module, class, function, attribute).
 
     Attributes
@@ -233,15 +248,6 @@ class Auto(_Base):
 
     kind: Literal["auto"] = "auto"
     name: str
-    members: Optional[list[str]] = None
-    include_private: bool = False
-    include_imports: bool = False
-    include_empty: bool = False
-    include: Optional[str] = None
-    exclude: Optional[str] = None
-    dynamic: Union[None, bool, str] = None
-    children: ChoicesChildren = ChoicesChildren.embedded
-    package: Union[str, None, MISSING] = MISSING()
 
 
 # TODO: rename to Default or something