Merge pull request #187 from machow/feat-subtitles

feat: add subtitle option to section

Author: machow

docs/_quarto.yml

@@ -131,38 +131,33 @@ quartodoc:
         - create_inventory
         - convert_inventory
 
-    - title: "Data models: structural"
+    - title: "Data models"
+
+    - subtitle: "Structural"
       desc: |
         Classes for specifying the broad structure your docs.
       contents:
-        - kind: "page"
-          path: "layouts-structure"
-          flatten: true
-          contents:
-            - layout.Layout
-            - layout.Section
-            - layout.Page
-            - layout.SectionElement
-            - layout.ContentElement
+        - layout.Layout
+        - layout.Section
+        - layout.Page
+        - layout.SectionElement
+        - layout.ContentElement
 
-    - title: "Data models: docable"
+    - subtitle: "Docable"
       desc: |
         Classes representing python objects to be rendered.
       contents:
-        - kind: "page"
-          path: "layouts-docable"
-          flatten: true
-          contents:
-            - name: layout.Doc
-              members: []
-            - layout.DocFunction
-            - layout.DocAttribute
-            - layout.DocModule
-            - layout.DocClass
-            - layout.Link
-            - layout.Item
-            - layout.ChoicesChildren
-    - title: "Data models: docstring patches"
+        - name: layout.Doc
+          members: []
+        - layout.DocFunction
+        - layout.DocAttribute
+        - layout.DocModule
+        - layout.DocClass
+        - layout.Link
+        - layout.Item
+        - layout.ChoicesChildren
+
+    - subtitle: "Docstring patches"
       desc: |
         Most of the classes for representing python objects live
         in [](`griffe.dataclasses`) or [](`griffe.docstrings.dataclasses`).

docs/get-started/basic-content.qmd

@@ -95,10 +95,36 @@ quartodoc:
         # set the children option, so that methods get documented
         # on separate pages. MdRenderer's docs will include a summary
         # table that links to each page.
-        - name: quartodoc.MdRenderer
+        - name: MdRenderer
           children: separate
 ```
 
+## Reference page sub-sections
+
+quartodoc supports two levels of grouping on the reference page.
+Use the `subtitle:` option to add an additional level of grouping.
+
+For example, the code below creates an API reference page with one top-level section ("Some section"),
+with two sub-sections inside it.
+
+
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: Some section
+
+    - subtitle: Stuff A
+      desc: This is subsection A
+      contents:
+        - MdRenderer
+
+    - subtitle: Stuff B
+      desc: This is subsection B
+      contents:
+        - get_object
+```
+
 ## Grouping on a page
 
 By default, content in each section gets included in the same index table,

docs/get-started/basic-docs.qmd

@@ -46,9 +46,10 @@ print(renderer.render(doc_params))
 
 The `sections` field defines which functions to document.
 
-It requires three pieces of configuration:
+It commonly requires three pieces of configuration:
 
 * `title`: a title for the section
 * `desc`: a description for the section
 * `contents`: a list of functions to document
 
+You can also replace `title` with `subtitle` to create a sub-section.

docs/styles.css

@@ -36,10 +36,29 @@ html { font-family: 'Inter', sans-serif; }
   line-height: 22px;
 }
 
+.sidebar-item {
+  margin-top: 0px;
+}
+
 .sidebar-item-section {
   padding-top: 16px;
 }
 
 .sidebar-section {
   padding-left: 0px !important;
 }
+
+.sidebar-item-section .sidebar-item-section {
+  padding-top: 0px;
+  padding-left: 10px;
+}
+
+
+td:first-child {
+  text-wrap: nowrap;
+  text-size-adjust: 100%;
+}
+
+td:first-child a {
+  word-break: normal;
+}

quartodoc/autosummary.py

@@ -572,12 +572,30 @@ def create_inventory(self, items):
 
     def _generate_sidebar(self, blueprint: layout.Layout):
         contents = [f"{self.dir}/index{self.out_page_suffix}"]
+        in_subsection = False
+        crnt_entry = {}
         for section in blueprint.sections:
+            if section.title:
+                if crnt_entry:
+                    contents.append(crnt_entry)
+
+                in_subsection = False
+                crnt_entry = {"section": section.title, "contents": []}
+            elif section.subtitle:
+                in_subsection = True
+
             links = []
             for entry in section.contents:
                 links.extend(self._page_to_links(entry))
 
-            contents.append({"section": section.title, "contents": links})
+            if in_subsection:
+                sub_entry = {"section": section.subtitle, "contents": links}
+                crnt_entry["contents"].append(sub_entry)
+            else:
+                crnt_entry["contents"].extend(links)
+
+        if crnt_entry:
+            contents.append(crnt_entry)
 
         entries = [{"id": self.dir, "contents": contents}, {"id": "dummy-sidebar"}]
         return {"website": {"sidebar": entries}}

quartodoc/layout.py

@@ -61,6 +61,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:
@@ -70,10 +73,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: ContentList = []
+
+    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 not self.contents:
+            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

@@ -547,16 +547,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/__snapshots__/test_builder.ambr

@@ -0,0 +1,20 @@
+# serializer version: 1
+# name: test_builder_generate_sidebar
+  '''
+  website:
+    sidebar:
+    - contents:
+      - reference/index.qmd
+      - contents:
+        - reference/a_func.qmd
+        section: first section
+      - contents:
+        - contents:
+          - reference/a_attr.qmd
+          section: a subsection
+        section: second section
+      id: reference
+    - id: dummy-sidebar
+  
+  '''
+# ---

quartodoc/tests/test_builder.py

@@ -1,8 +1,9 @@
 import pytest
+import yaml
 
 from pathlib import Path
 from quartodoc import layout as lo
-from quartodoc import Builder
+from quartodoc import Builder, blueprint
 
 
 @pytest.fixture
@@ -40,3 +41,28 @@ def test_builder_build_filter_wildcard_methods(builder):
     builder.build(filter="MdRenderer.*")
 
     len(list(Path(builder.dir).glob("Mdrenderer.*"))) == 2
+
+
+def test_builder_generate_sidebar(tmp_path, snapshot):
+    cfg = yaml.safe_load(
+        """
+    quartodoc:
+      package: quartodoc.tests.example
+      sections:
+        - title: first section
+          desc: some description
+          contents: [a_func]
+        - title: second section
+          desc: title description
+        - subtitle: a subsection
+          desc: subtitle description
+          contents:
+            - a_attr
+    """
+    )
+
+    builder = Builder.from_quarto_config(cfg)
+    bp = blueprint(builder.layout)
+    d_sidebar = builder._generate_sidebar(bp)
+
+    assert yaml.dump(d_sidebar) == snapshot

quartodoc/tests/test_layout.py

@@ -30,6 +30,20 @@ def test_layout_from_config(cfg, res):
     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]
+
+
 def test_layout_extra_forbidden():
     with pytest.raises(ValidationError) as exc_info:
         Section(title="abc", desc="xyz", contents=[], zzzzz=1)