Merge pull request #233 from machow/feat-option-defaults

Feat option defaults

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: |

docs/get-started/basic-content.qmd

@@ -99,6 +99,148 @@ quartodoc:
           children: separate
 ```
 
+
+## Setting default options
+
+The section above showed how you can set options like `members:` and `children:` on content.
+When specifying API documentation, you may need to specify the same options across multiple pieces of content.
+
+Use the `options:` field in a section to specify options to apply across all content in that section.
+
+For example, the config blocks below show how to document multiple classes without their members.
+
+:::::: {.columns}
+::: {.column}
+
+**Manual**
+
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: "Some section"
+
+      # options set manually ---
+      contents:
+        - name: MdRenderer
+          members: []
+        - name: Builder
+          members: []
+```
+
+:::
+::: {.column}
+
+**With options**
+
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: "Some section"
+
+      # default options ---
+      options:
+        members: []
+      
+      contents:
+        - MdRenderer
+        - Builder
+```
+
+:::
+::::::
+
+Note that the **with options** block sets `members: []` inside `options`.
+This sets `members: []` as the default for each piece of content.
+
+::: {.callout-tip}
+Options can be given a name, and re-used in multiple sections:
+
+```yaml
+- title: Some section
+  options: &no-members
+    members: []
+  content:
+    - ThingA
+    - ThingB
+- title: Another section
+  options: *no-members
+  content:
+    - ThingC
+```
+
+The code above uses `&no-members` to name the options in the first section "no-members",
+then `*no-members` to reference it in the second section.
+The `&` and `*` are called an anchor and alias, respectively, in YAML.
+:::
+
+## Specifying package path
+
+Different levels of configuration let you set the `package` option.
+This controls the package path that quartodoc will try to import control content from.
+
+The example below shows three different places it can be set:
+top-level site config, section config, or in a page element.
+
+```yaml
+# (1) package set on top-level site config
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: ""
+      desc: ""
+      contents:
+        - get_object         # quartodoc.get_object
+    
+    # (2) package set on a section
+    - title: ""
+      desc: ""
+      package: quartodoc.ast
+      contents:
+        - preview            # quartodoc.ast.preview
+
+        # (3) package set on a page
+        - kind: page
+          package: pandas
+          contents:
+            - DataFrame     # pandas.DataFrame
+        
+        # (4) package set on individual content entry
+        - package: pandas
+          name: Series
+```
+
+Use `package: null` to unset the package option. This enables you to specify objects using their full name.
+
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: ""
+      desc: ""
+      package: null
+      contents:
+        - quartodoc.get_object
+```
+
+
+## Dynamic lookup
+
+By default, quartodoc uses static analysis to look up objects.
+This means it gets information about your docstring without actually running your package's code.
+
+This usually works well, but may get the docstring wrong for those created in an extremely dynamic way (e.g. you manually set the `__doc__` attribute on an object).
+
+In this case, you can set the dynamic option on a piece of content.
+
+```yaml
+contents:
+  - name: get_object
+    dynamic: true
+```
+
+
 ## Reference page sub-sections
 
 quartodoc supports two levels of grouping on the reference page.
@@ -210,67 +352,3 @@ Note these three important pieces of the page entry:
 * `contents:` - lists out the contents of the page.
 
 
-
-## Setting default package path
-
-Different levels of configuration let you set the `package` option.
-This controls the package path that quartodoc will try to import control content from.
-
-The example below shows three different places it can be set:
-top-level site config, section config, or in a page element.
-
-```yaml
-# (1) package set on top-level site config
-quartodoc:
-  package: quartodoc
-  sections:
-    - title: ""
-      desc: ""
-      contents:
-        - get_object         # quartodoc.get_object
-    
-    # (2) package set on a section
-    - title: ""
-      desc: ""
-      package: quartodoc.ast
-      contents:
-        - preview            # quartodoc.ast.preview
-
-        # (3) package set on a page
-        - kind: page
-          package: pandas
-          contents:
-            - DataFrame     # pandas.DataFrame
-        
-        # (4) package set on individual content entry
-        - package: pandas
-          name: Series
-```
-
-Use `package: null` to unset the package option. This enables you to specify objects using their full name.
-
-```yaml
-quartodoc:
-  package: quartodoc
-  sections:
-    - title: ""
-      desc: ""
-      package: null
-      contents:
-        - quartodoc.get_object
-```
-
-## Dynamic lookup
-
-By default, quartodoc uses static analysis to look up objects.
-This means it gets information about your docstring without actually running your package's code.
-
-This usually works well, but may get the docstring wrong for those created in an extremely dynamic way (e.g. you manually set the `__doc__` attribute on an object).
-
-In this case, you can set the dynamic option on a piece of content.
-
-```yaml
-contents:
-  - name: get_object
-    dynamic: true
-```

quartodoc/builder/blueprint.py

@@ -29,10 +29,14 @@
 
 from .utils import PydanticTransformer, ctx_node, WorkaroundKeyError
 
-from typing import overload
+from typing import overload, TYPE_CHECKING
+
 
 _log = logging.getLogger(__name__)
 
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
 
 def _auto_package(mod: dc.Module) -> list[Section]:
     """Create default sections for the given package."""
@@ -86,13 +90,24 @@ def _is_external_alias(obj: dc.Alias | dc.Object, mod: dc.Module):
     return False
 
 
-def _to_simple_dict(el):
+def _to_simple_dict(el: "BaseModel"):
     # round-trip to json, so we can take advantage of pydantic
     # dumping Enums, etc.. There may be a simple way to do
     # this in pydantic v2.
     return json.loads(el.json(exclude_unset=True))
 
 
+def _non_default_entries(el: "BaseModel"):
+    field_defaults = {mf.name: mf.default for mf in el.__fields__.values()}
+    set_fields = [
+        k for k, v in el if field_defaults[k] is not v if not isinstance(v, MISSING)
+    ]
+
+    d = el.dict()
+
+    return {k: d[k] for k in set_fields}
+
+
 class BlueprintTransformer(PydanticTransformer):
     def __init__(self, get_object=None, parser="numpy"):
 
@@ -107,7 +122,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 +154,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 +234,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 +244,14 @@ 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?
+            _option_dict = _non_default_entries(self.options)
+            _el_dict = _non_default_entries(el)
+            el = el.__class__(**{**_option_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