fix: handle subtitles in sidebar

Author: machow

docs/_quarto.yml

@@ -130,38 +130,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/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

@@ -558,12 +558,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)
 
         return {"website": {"sidebar": {"id": self.dir, "contents": contents}}}
 

quartodoc/layout.py

@@ -74,13 +74,13 @@ class Section(_Structural):
     subtitle: Optional[str] = None
     desc: Optional[str] = None
     package: Union[str, None, MISSING] = MISSING()
-    contents: Optional[ContentList] = None
+    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 self.contents is None:
+        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"
             )