Feat include filters

docs/get-started/basic-content.qmd

@@ -154,7 +154,8 @@ quartodoc:
 Note that the **with options** block sets `members: []` inside `options`.
 This sets `members: []` as the default for each piece of content.
 
-::: {.callout-tip}
+### Reusing options
+
 Options can be given a name, and re-used in multiple sections:
 
 ```yaml
@@ -173,7 +174,31 @@ Options can be given a name, and re-used in multiple sections:
 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.
-:::
+
+
+### Where to put options
+
+You can specify options in either the top-level config, or individual Sections.
+
+```yaml
+quartodoc:
+  package: quartodoc
+
+  # set options on the top-level config.
+  # this will apply to all pieces of content.
+  options:
+    include_attributes: false
+  sections:
+    - contents:
+        - MdRenderer
+
+      # set options in an individual section.
+      # in thise case, it resets include_attributes back
+      # to defaulting as true
+      options:
+        include_attributes: true
+
+```
 
 ## Specifying package path
 

quartodoc/autosummary.py

@@ -378,6 +378,8 @@ class Builder:
         Title of the API index page.
     renderer: Renderer
         The renderer used to convert docstrings (e.g. to markdown).
+    options:
+        Default options to set for all pieces of content (e.g. include_attributes).
     out_index:
         The output path of the index file, used to list all API functions.
     sidebar:
@@ -429,6 +431,7 @@ def __init__(
         package: str,
         # TODO: correct typing
         sections: "list[Any]" = tuple(),
+        options: "dict | None" = None,
         version: "str | None" = None,
         dir: str = "reference",
         title: str = "Function reference",
@@ -440,7 +443,9 @@ def __init__(
         dynamic: bool | None = None,
         parser="numpy",
     ):
-        self.layout = self.load_layout(sections=sections, package=package)
+        self.layout = self.load_layout(
+            sections=sections, package=package, options=options
+        )
 
         self.package = package
         self.version = None
@@ -458,12 +463,12 @@ def __init__(
         self.source_dir = str(Path(source_dir).absolute()) if source_dir else None
         self.dynamic = dynamic
 
-    def load_layout(self, sections: dict, package: str):
+    def load_layout(self, sections: dict, package: str, options=None):
         # TODO: currently returning the list of sections, to make work with
         # previous code. We should make Layout a first-class citizen of the
         # process.
         try:
-            return layout.Layout(sections=sections, package=package)
+            return layout.Layout(sections=sections, package=package, options=options)
         except ValidationError as e:
             msg = "Configuration error for YAML:\n - "
             errors = [fmt(err) for err in e.errors() if fmt(err)]

quartodoc/builder/blueprint.py

@@ -330,7 +330,7 @@ def _fetch_members(el: Auto, obj: dc.Object | dc.Alias):
         if el.members is not None:
             return el.members
 
-        options = obj.members
+        options = obj.all_members if el.include_inherited else obj.members
 
         if el.include:
             raise NotImplementedError("include argument currently unsupported.")
@@ -341,12 +341,21 @@ def _fetch_members(el: Auto, obj: dc.Object | dc.Alias):
         if not el.include_private:
             options = {k: v for k, v in options.items() if not k.startswith("_")}
 
-        if not el.include_imports:
+        if not el.include_imports and not el.include_inherited:
             options = {k: v for k, v in options.items() if not v.is_alias}
 
         if not el.include_empty:
             options = {k: v for k, v in options.items() if v.docstring is not None}
 
+        if not el.include_attributes:
+            options = {k: v for k, v in options.items() if not v.is_attribute}
+
+        if not el.include_classes:
+            options = {k: v for k, v in options.items() if not v.is_class}
+
+        if not el.include_functions:
+            options = {k: v for k, v in options.items() if not v.is_function}
+
         # for modules, remove any Alias objects, since they were imported from
         # other places. Sphinx has a flag for this behavior, so may be good
         # to do something similar.

quartodoc/layout.py

@@ -48,6 +48,7 @@ class Layout(_Structural):
 
     sections: list[Union[SectionElement, Section]] = []
     package: Union[str, None, MISSING] = MISSING()
+    options: Optional["AutoOptions"] = None
 
 
 # SubElements -----------------------------------------------------------------
@@ -207,6 +208,14 @@ class AutoOptions(_Base):
     include_private: bool = False
     include_imports: bool = False
     include_empty: bool = False
+    include_inherited: bool = False
+
+    # member types to include ----
+    include_attributes: bool = True
+    include_classes: bool = True
+    include_functions: bool = True
+
+    # other options ----
     include: Optional[str] = None
     exclude: Optional[str] = None
     dynamic: Union[None, bool, str] = None
@@ -230,6 +239,14 @@ class Auto(AutoOptions):
         Whether to include members that were imported from somewhere else.
     include_empty:
         Whether to include members with no docstring.
+    include_inherited:
+        Whether to include members inherited from a parent class.
+    include_attributes:
+        Whether to include attributes.
+    include_classes:
+        Whether to include classes.
+    include_functions:
+        Whether to include functions.
     include:
         (Not implemented). A list of members to include.
     exclude:

quartodoc/tests/__snapshots__/test_renderers.ambr

@@ -25,6 +25,18 @@
   | [some_property](#quartodoc.tests.example_class.C.some_property) | A property |
   | [z](#quartodoc.tests.example_class.C.z) | A documented init attribute |
 
+  ## Classes
+
+  | Name | Description |
+  | --- | --- |
+  | [D](#quartodoc.tests.example_class.C.D) | A nested class |
+
+  ### D { #quartodoc.tests.example_class.C.D }
+
+  `tests.example_class.C.D()`
+
+  A nested class
+
   ## Methods
 
   | Name | Description |
@@ -64,6 +76,18 @@
   | [some_property](#quartodoc.tests.example_class.C.some_property) | A property |
   | [z](#quartodoc.tests.example_class.C.z) | A documented init attribute |
 
+  ## Classes
+
+  | Name | Description |
+  | --- | --- |
+  | [D](#quartodoc.tests.example_class.C.D) | A nested class |
+
+  ## D { #quartodoc.tests.example_class.C.D }
+
+  `tests.example_class.C.D()`
+
+  A nested class
+
   ## Methods
 
   | Name | Description |

quartodoc/tests/example_class.py

@@ -29,6 +29,14 @@ def some_method(self):
     def some_property(self):
         """A property"""
 
+    class D:
+        """A nested class"""
+
+
+class Child(C):
+    def some_new_method(self):
+        """A new method"""
+
 
 class AttributesTable:
     """The short summary.

quartodoc/tests/test_builder.py

@@ -43,6 +43,22 @@ def test_builder_build_filter_wildcard_methods(builder):
     len(list(Path(builder.dir).glob("Mdrenderer.*"))) == 2
 
 
+def test_builder_auto_options():
+    cfg = yaml.safe_load(
+        """
+    quartodoc:
+      package: quartodoc
+      options:
+        members: [a_func, a_attr]
+      sections:
+        - contents: [quartodoc.tests.example]
+    """
+    )
+
+    builder = Builder.from_quarto_config(cfg)
+    assert builder.layout.options.members == ["a_func", "a_attr"]
+
+
 def test_builder_generate_sidebar(tmp_path, snapshot):
     cfg = yaml.safe_load(
         """

quartodoc/tests/test_builder_blueprint.py

@@ -119,6 +119,24 @@ def test_blueprint_auto_package(bp):
     assert len(sections[0].contents) == 4
 
 
+def test_blueprint_layout_options():
+    layout = lo.Layout(
+        options={"members": []},
+        sections=[
+            lo.Section(
+                contents=[lo.Auto(name="AClass")],
+                package="quartodoc.tests.example",
+            )
+        ],
+    )
+
+    res = blueprint(layout)
+    page = res.sections[0].contents[0]
+    doc = page.contents[0]
+
+    assert doc.members == []
+
+
 def test_blueprint_section_options():
     layout = lo.Layout(
         sections=[
@@ -135,3 +153,33 @@ def test_blueprint_section_options():
     doc = page.contents[0]
 
     assert doc.members == []
+
+
+def _check_member_names(members, expected):
+    member_names = set([entry.name for entry in members])
+    assert member_names == expected
+
+
+@pytest.mark.parametrize(
+    "kind, removed",
+    [
+        ("attributes", {"some_property", "z", "SOME_ATTRIBUTE"}),
+        ("classes", {"D"}),
+        ("functions", {"some_method"}),
+    ],
+)
+def test_blueprint_fetch_members_include_kind_false(kind, removed):
+    option = {f"include_{kind}": False}
+    all_members = {"SOME_ATTRIBUTE", "z", "some_property", "some_method", "D"}
+
+    auto = lo.Auto(name="quartodoc.tests.example_class.C", **option)
+    bp = blueprint(auto)
+    _check_member_names(bp.members, all_members - removed)
+
+
+def test_blueprint_fetch_members_include_inherited():
+    auto = lo.Auto(name="quartodoc.tests.example_class.Child", include_inherited=True)
+    bp = blueprint(auto)
+
+    member_names = set([entry.name for entry in bp.members])
+    assert "some_method" in member_names