feat: add subtitle option to section

Author: machow

quartodoc/layout.py

@@ -58,6 +58,9 @@ class Section(_Structural):
     kind:
     title:
         Title of the section on the index.
+    subtitle:
+        Subtitle of the section on the index. Note that either title or subtitle,
+        but not both, may be set.
     desc:
         Description of the section on the index.
     package:
@@ -67,10 +70,22 @@ class Section(_Structural):
     """
 
     kind: Literal["section"] = "section"
-    title: str
-    desc: str
+    title: Optional[str] = None
+    subtitle: Optional[str] = None
+    desc: Optional[str] = None
     package: Union[str, None, MISSING] = MISSING()
-    contents: ContentList
+    contents: Optional[ContentList] = None
+
+    def __init__(self, **data):
+        super().__init__(**data)
+
+        # TODO: should these be a custom type? Or can we use pydantic's ValidationError?
+        if self.title is None and self.subtitle is None and self.contents is None:
+            raise ValueError(
+                "Section must specify a title, subtitle, or contents field"
+            )
+        elif self.title is not None and self.subtitle is not None:
+            raise ValueError("Section cannot specify both title and subtitle fields.")
 
 
 class SummaryDetails(_Base):

quartodoc/renderers/md_renderer.py

@@ -528,16 +528,23 @@ def summarize(self, el: layout.Layout):
 
     @dispatch
     def summarize(self, el: layout.Section):
-        header = f"## {el.title}\n\n{el.desc}"
+        desc = f"\n\n{el.desc}" if el.desc is not None else ""
+        if el.title is not None:
+            header = f"## {el.title}{desc}"
+        elif el.subtitle is not None:
+            header = f"### {el.subtitle}{desc}"
 
-        thead = "| | |\n| --- | --- |"
+        if el.contents:
+            thead = "| | |\n| --- | --- |"
 
-        rendered = []
-        for child in el.contents:
-            rendered.append(self.summarize(child))
+            rendered = []
+            for child in el.contents:
+                rendered.append(self.summarize(child))
 
-        str_func_table = "\n".join([thead, *rendered])
-        return f"{header}\n\n{str_func_table}"
+            str_func_table = "\n".join([thead, *rendered])
+            return f"{header}\n\n{str_func_table}"
+        
+        return header
 
     @dispatch
     def summarize(self, el: layout.Page):

quartodoc/tests/test_layout.py

@@ -27,3 +27,17 @@ def test_layout_from_config(cfg, res):
 
     layout = Layout(sections=[cfg])
     assert layout.sections[0] == res
+
+
+@pytest.mark.parametrize(
+    "kwargs, msg_part",
+    [
+        ({}, "must specify a title, subtitle, or contents field"),
+        ({"title": "x", "subtitle": "y"}, "cannot specify both"),
+    ],
+)
+def test_section_validation_fails(kwargs, msg_part):
+    with pytest.raises(ValueError) as exc_info:
+        Section(**kwargs)
+
+    assert msg_part in exc_info.value.args[0]

quartodoc/tests/test_renderers.py

@@ -2,7 +2,8 @@
 import griffe.docstrings.dataclasses as ds
 
 from quartodoc.renderers import MdRenderer
-from quartodoc import get_object
+from quartodoc import layout
+from quartodoc import get_object, blueprint
 
 
 @pytest.fixture
@@ -60,3 +61,30 @@ def test_render_table_description_interlink(renderer, pair):
 
     res = renderer.render(pars)
     assert interlink in res
+
+
+@pytest.mark.parametrize(
+    "section, dst",
+    [
+        (layout.Section(title="abc"), "## abc"),
+        (layout.Section(subtitle="abc"), "### abc"),
+        (layout.Section(title="abc", desc="zzz"), "## abc\n\nzzz"),
+        (layout.Section(subtitle="abc", desc="zzz"), "### abc\n\nzzz"),
+    ],
+)
+def test_render_summarize_section_title(renderer, section, dst):
+    res = renderer.summarize(section)
+
+    assert res == dst
+
+
+def test_render_summarize_section_contents(renderer):
+    obj = blueprint(layout.Auto(name="a_func", package="quartodoc.tests.example"))
+    section = layout.Section(title="abc", desc="zzz", contents=[obj])
+    res = renderer.summarize(section)
+
+    table = (
+        "| | |\n| --- | --- |\n"
+        "| [a_func](#quartodoc.tests.example.a_func) | A function |"
+    )
+    assert res == f"## abc\n\nzzz\n\n{table}"