feat: autogenerate site content if no sections specified

Author: machow

quartodoc/autosummary.py

@@ -416,7 +416,8 @@ def __init_subclass__(cls, **kwargs):
     def __init__(
         self,
         package: str,
-        sections: "list[Any]",
+        # TODO: correct typing
+        sections: "list[Any]" = tuple(),
         version: "str | None" = None,
         dir: str = "reference",
         title: str = "Function reference",
@@ -451,10 +452,12 @@ def load_layout(self, sections: dict, package: str):
         try:
             return layout.Layout(sections=sections, package=package)
         except ValidationError as e:
-            msg = 'Configuration error for YAML:\n - '
+            msg = "Configuration error for YAML:\n - "
             errors = [fmt(err) for err in e.errors() if fmt(err)]
-            first_error = errors[0] # we only want to show one error at a time b/c it is confusing otherwise
-            msg += first_error           
+            first_error = errors[
+                0
+            ]  # we only want to show one error at a time b/c it is confusing otherwise
+            msg += first_error
             raise ValueError(msg) from None
 
     # building ----------------------------------------------------------------

quartodoc/builder/blueprint.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import logging
+import json
+import yaml
 
 from griffe import dataclasses as dc
 from griffe.loader import GriffeLoader
@@ -31,6 +33,36 @@
 _log = logging.getLogger(__name__)
 
 
+def _auto_package(mod: dc.Module) -> list[Section]:
+    """Create default sections for the given package."""
+
+    import griffe.docstrings.dataclasses as ds
+
+    # get module members for content ----
+    contents = []
+    for name, member in mod.members.items():
+        if member.is_module or name.startswith("__all__"):
+            continue
+
+        contents.append(Auto(name=name))
+
+    # try to fetch a description of the module ----
+    mod_summary = mod.docstring.parsed[0]
+    if isinstance(mod_summary, ds.DocstringSectionText):
+        desc = mod_summary.value
+    else:
+        desc = ""
+
+    return [Section(title=mod.name, desc=desc, contents=contents)]
+
+
+def _to_simple_dict(el):
+    # 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))
+
+
 class BlueprintTransformer(PydanticTransformer):
     def __init__(self, get_object=None, parser="numpy"):
 
@@ -80,6 +112,37 @@ def visit(self, el):
         finally:
             self.crnt_package = old
 
+    @dispatch
+    def enter(self, el: Layout):
+        if not el.sections:
+            # TODO: should be shown all the time, not just logged,
+            # but also want to be able to disable (similar to pins)
+            print("Autogenerating contents (since no contents specified in config)")
+
+            package = el.package
+
+            mod = self.get_object_fixed(package)
+            sections = _auto_package(mod)
+
+            if not sections:
+                # TODO: informative message. When would this occur?
+                raise ValueError()
+
+            new_el = el.copy()
+            new_el.sections = sections
+
+            print(
+                "Use the following config configuration to recreate the automatically",
+                " generated site:\n\n\n",
+                yaml.safe_dump(_to_simple_dict(new_el)),
+                "\n",
+                sep="",
+            )
+
+            return super().enter(new_el)
+
+        return super().enter(el)
+
     @dispatch
     def exit(self, el: Section):
         """Transform top-level sections, so their contents are all Pages."""
@@ -178,8 +241,8 @@ def _fetch_members(el: Auto, obj: dc.Object | dc.Alias):
         # 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.
-        if obj.is_module:
-            options = {k: v for k, v in options.items() if not v.is_alias}
+        # if obj.is_module:
+        #    options = {k: v for k, v in options.items() if not v.is_alias}
 
         return sorted(options)
 

quartodoc/layout.py

@@ -46,7 +46,7 @@ class Layout(_Structural):
         The package being documented.
     """
 
-    sections: list[Union[SectionElement, Section]]
+    sections: list[Union[SectionElement, Section]] = []
     package: Union[str, None, MISSING] = MISSING()