feat: filter argument for Builder and CLI

Author: machow

quartodoc/__main__.py

@@ -42,9 +42,10 @@ def cli():
 
 @click.command()
 @click.argument("config", default="_quarto.yml")
+@click.option("--filter", nargs=1, default="*")
 @click.option("--dry-run", is_flag=True, default=False)
 @click.option("--verbose", is_flag=True, default=False)
-def build(config, dry_run, verbose):
+def build(config, filter, dry_run, verbose):
     if verbose:
         _enable_logs()
 
@@ -55,7 +56,7 @@ def build(config, dry_run, verbose):
         pass
     else:
         with chdir(Path(config).parent):
-            builder.build()
+            builder.build(filter=filter)
 
 
 @click.command()

quartodoc/autosummary.py

@@ -4,6 +4,7 @@
 import warnings
 import yaml
 
+from fnmatch import fnmatchcase
 from griffe.loader import GriffeLoader
 from griffe.collections import ModulesCollection, LinesCollection
 from griffe.dataclasses import Alias
@@ -375,7 +376,7 @@ def __init__(
         renderer: "dict | Renderer | str" = "markdown",
         out_index: str = None,
         sidebar: "str | None" = None,
-        rewrite_all_pages=True,
+        rewrite_all_pages=False,
     ):
         self.layout = self.load_layout(sections=sections, package=package)
 
@@ -400,8 +401,16 @@ def load_layout(self, sections: dict, package: str):
 
     # building ----------------------------------------------------------------
 
-    def build(self):
-        """Build index page, sphinx inventory, and individual doc pages."""
+    def build(self, filter: str = "*"):
+        """Build index page, sphinx inventory, and individual doc pages.
+
+        Parameters
+        ----------
+        filter:
+            A simple pattern, that may include * as a wildcard. If specified,
+            only doc paths for objects with matching names will be written.
+            Path is the file's base name in the API dir (e.g. MdRenderer.render)
+        """
 
         from quartodoc import blueprint, collect
 
@@ -419,7 +428,7 @@ def build(self):
         self.write_index(blueprint)
 
         _log.info("Writing docs pages")
-        self.write_doc_pages(pages)
+        self.write_doc_pages(pages, filter)
 
         # inventory ----
 
@@ -448,7 +457,7 @@ def write_index(self, blueprint: layout.Layout):
 
         return str(p_index)
 
-    def write_doc_pages(self, pages):
+    def write_doc_pages(self, pages, filter: str):
         """Write individual function documentation pages."""
 
         for page in pages:
@@ -460,13 +469,24 @@ def write_doc_pages(self, pages):
             # Only write out page if it has changed, or we've set the
             # rewrite_all_pages option. This ensures that quarto won't have
             # to re-render every page of the API all the time.
+            if filter != "*":
+                is_match = fnmatchcase(page.path, filter)
+
+                if is_match:
+                    _log.info("Matched filter")
+                else:
+                    _log.info("Skipping write (no filter match)")
+                    continue
+
             if (
                 self.rewrite_all_pages
                 or (not html_path.exists())
                 or (html_path.read_text() != rendered)
             ):
-                _log.info(f"Writing {page.path}")
+                _log.info(f"Writing: {page.path}")
                 html_path.write_text(rendered)
+            else:
+                _log.info("Skipping write (content unchanged)")
 
     # inventory ----
 

quartodoc/tests/test_builder.py

@@ -0,0 +1,42 @@
+import pytest
+
+from pathlib import Path
+from quartodoc import layout as lo
+from quartodoc import Builder
+
+
+@pytest.fixture
+def builder(tmp_path):
+    section = lo.Section(
+        title="abc",
+        desc="xyz",
+        contents=[
+            lo.Auto(name="get_object"),
+            lo.Auto(
+                name="MdRenderer", members=["render", "summarize"], children="separate"
+            ),
+        ],
+    )
+
+    builder = Builder(package="quartodoc", sections=[section], dir=str(tmp_path))
+
+    yield builder
+
+
+def test_builder_build_filter_simple(builder):
+    builder.build(filter="get_object")
+
+    assert (Path(builder.dir) / "get_object.qmd").exists()
+    assert not (Path(builder.dir) / "MdRenderer.qmd").exists()
+
+
+def test_builder_build_filter_wildcard_class(builder):
+    builder.build(filter="MdRenderer*")
+
+    len(list(Path(builder.dir).glob("Mdrenderer*"))) == 3
+
+
+def test_builder_build_filter_wildcard_methods(builder):
+    builder.build(filter="MdRenderer.*")
+
+    len(list(Path(builder.dir).glob("Mdrenderer.*"))) == 2