clear-skies-doc-builder 2.0.7__py3-none-any.whl → 2.0.9__py3-none-any.whl

{clear_skies_doc_builder-2.0.7.dist-info → clear_skies_doc_builder-2.0.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clear-skies-doc-builder
-Version: 2.0.7
+Version: 2.0.9
 Summary: The docbuilder for all 'official' clearskies plugins (as well as the main clearskies docs)
 Project-URL: repository, https://github.com/clearskies-py/docs
 Project-URL: issues, https://github.com/clearskies-py/docs/issues
@@ -142,6 +142,38 @@ This creates:
 
 The `grand_parent` field enables the Jekyll "just-the-docs" theme's three-level navigation, allowing you to document submodule classes under their logical grouping.
 
+#### Parent-Only Sections (No Classes)
+
+You can create a parent section that only serves as a navigation container without documenting any classes directly. This is useful when you want to group multiple submodules under a common heading:
+
+```json
+{
+  "tree": [
+    {
+      "title": "Cursors",
+      "source": "clearskies.cursors.Cursor",
+      "builder": "clearskies_doc_builder.builders.Module"
+    },
+    {
+      "title": "IAM Cursors",
+      "source": "clearskies.cursors.iam.IamCursor",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "parent": "Cursors",
+      "classes": ["clearskies.cursors.iam.RdsMysql"]
+    },
+    {
+      "title": "Port Forwarding",
+      "source": "clearskies.cursors.port_forwarding.PortForwarder",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "parent": "Cursors",
+      "classes": ["clearskies.cursors.port_forwarding.Ssm"]
+    }
+  ]
+}
+```
+
+Note that the "Cursors" entry has no `classes` field - it just creates an index page with the overview from the source class docblock. The child sections ("IAM Cursors" and "Port Forwarding") will appear as sub-navigation items under "Cursors".
+
 #### Using SingleClass for Individual Classes
 
 You can also use `SingleClass` builder for documenting individual classes within a hierarchy:
@@ -163,3 +195,75 @@ You can also use `SingleClass` builder for documenting individual classes within
   ]
 }
 ```
+
+### Automatic Navigation Ordering
+
+Child entries under a parent are automatically sorted so that submodules appear first (alphabetically), followed by individual classes (alphabetically). The entry type is **automatically inferred** from the builder:
+
+- **`Module` builder** → treated as "submodule" (appears first)
+- **`SingleClass` / `SingleClassToSection` builder** → treated as "class" (appears after submodules)
+- **Other builders** → appear last
+
+#### Example
+
+```json
+{
+  "tree": [
+    {
+      "title": "Cursors",
+      "source": "clearskies.cursors.Cursor",
+      "builder": "clearskies_doc_builder.builders.Module"
+    },
+    {
+      "title": "Memory Cursor",
+      "source": "clearskies.cursors.MemoryCursor",
+      "builder": "clearskies_doc_builder.builders.SingleClass",
+      "parent": "Cursors"
+    },
+    {
+      "title": "File Cursor",
+      "source": "clearskies.cursors.FileCursor",
+      "builder": "clearskies_doc_builder.builders.SingleClass",
+      "parent": "Cursors"
+    },
+    {
+      "title": "From Environment",
+      "source": "clearskies.cursors.from_environment.FromEnvironmentBase",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "parent": "Cursors",
+      "classes": ["clearskies.cursors.from_environment.EnvCursor"]
+    },
+    {
+      "title": "AWS",
+      "source": "clearskies.cursors.aws.AWSBase",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "parent": "Cursors",
+      "classes": ["clearskies.cursors.aws.SecretsManager"]
+    }
+  ]
+}
+```
+
+This will generate navigation in the following order under "Cursors":
+1. **AWS** (Module builder = submodule, alphabetically first)
+2. **From Environment** (Module builder = submodule, alphabetically second)
+3. **File Cursor** (SingleClass builder = class, alphabetically first)
+4. **Memory Cursor** (SingleClass builder = class, alphabetically second)
+
+This ensures a consistent navigation structure where submodules (which typically contain multiple classes) are grouped together at the top, followed by individual class documentation.
+
+#### Manual Override with `entry_type`
+
+If needed, you can explicitly set `entry_type` to override the automatic inference:
+
+```json
+{
+  "title": "Special Entry",
+  "source": "...",
+  "builder": "clearskies_doc_builder.builders.SingleClass",
+  "parent": "Cursors",
+  "entry_type": "submodule"
+}
+```
+
+Supported values: `"submodule"`, `"class"`, or omit for default behavior.

{clear_skies_doc_builder-2.0.7.dist-info → clear_skies_doc_builder-2.0.9.dist-info}/RECORD

@@ -1,5 +1,5 @@
 clearskies_doc_builder/__init__.py,sha256=AFQzZ9HwIxPyLpsUhkSDRh_6hm8-5H4RpAelTShCDTc,1300
-clearskies_doc_builder/build_callable.py,sha256=sCjXSnqFU-27zr2-i5D5I3M0ebDWO4OEvikvSNQg6oA,1608
+clearskies_doc_builder/build_callable.py,sha256=DjPGTXD9mwwhCzTFSVcEPOHAU4Nn6yWjPf8ZJQBn-WQ,3758
 clearskies_doc_builder/prepare_doc_space.py,sha256=BXIH-CQJ1ZY6sf2bj1Fjhrglihls6AnqMNdjirDqSFM,1019
 clearskies_doc_builder/backends/__init__.py,sha256=q5jpy8xfZ4SbGQ1T30q4mp4h346HaMivvmNqtgTMQxw,303
 clearskies_doc_builder/backends/attribute_backend.py,sha256=2nivmJpedPsoQibf9NlIT-Wfvg0PbfHKoT06xKkt0O0,3634
@@ -8,7 +8,7 @@ clearskies_doc_builder/backends/module_backend.py,sha256=hHJXt00TJIF3-69p_kjdAZu
 clearskies_doc_builder/backends/python.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clearskies_doc_builder/builders/__init__.py,sha256=ndAK4-imR9vhl7CS425ASYi46FN5-eR9Dr6bKxCn5lA,292
 clearskies_doc_builder/builders/builder.py,sha256=2QZDscwOZ4vfx4NzFU4AyKgAPuKVU0jsYBcT42CZgzY,7957
-clearskies_doc_builder/builders/module.py,sha256=WlLSMPN3AoCaMg66DxvRXiO3x4zVFhoYGXjHM6U0M6c,4912
+clearskies_doc_builder/builders/module.py,sha256=tPtXcqmI-XG-yH82WdmK4MLBL73RMiAHL_0VOJZaIKw,4920
 clearskies_doc_builder/builders/single_class.py,sha256=-3b9VC_bxB9r5EHcdUCA1VFWxY0r_N72td0ZHLydy3Y,4846
 clearskies_doc_builder/builders/single_class_to_section.py,sha256=uEyawxW4cIdavBVnK2TBiIqywUgj3IxmUcS16E81cgI,1754
 clearskies_doc_builder/columns/__init__.py,sha256=--cof8kFPwlZncM3MBQYkvfq8TejEeI0B99vTlEVCkU,566
@@ -32,7 +32,7 @@ clearskies_doc_builder/models/method_reference.py,sha256=U4YOpRLotyEp6G0Y5OHORdo
 clearskies_doc_builder/models/module.py,sha256=5JUF2LUKTpVsYlviT7T_qgLdMApGtS4qIUloCEzJ-uo,573
 clearskies_doc_builder/models/module_reference.py,sha256=-zHnrkP6JR7j2XFuW94uGlPENI3ZshxgBu4yY9ayzSg,177
 clearskies_doc_builder/models/property.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-clear_skies_doc_builder-2.0.7.dist-info/METADATA,sha256=vOVE5Aqo5BiuVRm3QdwiE5FHfelXSRvRS_2OfKkwo_A,7036
-clear_skies_doc_builder-2.0.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-clear_skies_doc_builder-2.0.7.dist-info/licenses/LICENSE,sha256=pgH32-xrgpIDf6WIBUA1X19o-sIHIXgToCxo-tBWDdw,1071
-clear_skies_doc_builder-2.0.7.dist-info/RECORD,,
+clear_skies_doc_builder-2.0.9.dist-info/METADATA,sha256=NySZL3qttV4RKPaSOZQdp4r1ysct3CPa_8NT-O_3IFY,10626
+clear_skies_doc_builder-2.0.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+clear_skies_doc_builder-2.0.9.dist-info/licenses/LICENSE,sha256=pgH32-xrgpIDf6WIBUA1X19o-sIHIXgToCxo-tBWDdw,1071
+clear_skies_doc_builder-2.0.9.dist-info/RECORD,,

clearskies_doc_builder/build_callable.py

@@ -4,29 +4,97 @@ from clearskies_doc_builder import models
 from clearskies_doc_builder.prepare_doc_space import prepare_doc_space
 
 
+def _infer_entry_type(entry: dict[str, Any]) -> str:
+    """
+    Infer the entry type from the builder class name.
+
+    - Module builder -> "submodule" (contains multiple classes, acts as a section)
+    - SingleClass builder -> "class" (documents a single class)
+    - SingleClassToSection builder -> "class"
+    - Other/unknown -> "" (will be sorted last)
+
+    This can be overridden by explicitly setting "entry_type" in the config.
+    """
+    # Allow explicit override
+    if "entry_type" in entry:
+        return entry["entry_type"]
+
+    builder = entry.get("builder", "")
+    if builder.endswith(".Module"):
+        return "submodule"
+    elif builder.endswith(".SingleClass") or builder.endswith(".SingleClassToSection"):
+        return "class"
+    return ""
+
+
+def _sort_key_for_entry(entry: dict[str, Any]) -> tuple[int, str]:
+    """
+    Generate a sort key for navigation ordering.
+
+    Entries are sorted by:
+    1. entry_type priority: "submodule" (0) comes before "class" (1) and others (2)
+    2. title alphabetically (case-insensitive)
+
+    This ensures submodules appear first in navigation, followed by classes,
+    all sorted alphabetically within their group.
+
+    Entry type is automatically inferred from the builder:
+    - Module builder -> "submodule"
+    - SingleClass/SingleClassToSection builder -> "class"
+    """
+    entry_type = _infer_entry_type(entry)
+    type_priority = {"submodule": 0, "class": 1}.get(entry_type, 2)
+    title = entry.get("title", "").lower()
+    return (type_priority, title)
+
+
+def _compute_nav_orders(tree: list[dict[str, Any]]) -> dict[int, int]:
+    """
+    Compute nav_order for each entry in the tree based on sorting rules.
+
+    Returns a dict mapping original tree index to computed nav_order.
+
+    For entries with the same parent:
+    - Groups by entry_type (submodules first, then classes)
+    - Sorts alphabetically within each group
+    - Assigns sequential nav_order values
+
+    Top-level entries maintain their original order (index + 2).
+    """
+    # Group entries by their parent
+    parent_groups: dict[str | None, list[tuple[int, dict[str, Any]]]] = {}
+
+    for index, entry in enumerate(tree):
+        parent = entry.get("parent")
+        if parent not in parent_groups:
+            parent_groups[parent] = []
+        parent_groups[parent].append((index, entry))
+
+    # Compute nav_order for each entry
+    nav_orders: dict[int, int] = {}
+
+    for parent, entries in parent_groups.items():
+        if parent is None:
+            # Top-level entries: use original index-based ordering
+            for original_index, entry in entries:
+                nav_orders[original_index] = original_index + 2
+        else:
+            # Child entries: sort by type then alphabetically
+            sorted_entries = sorted(entries, key=lambda x: _sort_key_for_entry(x[1]))
+            for nav_order, (original_index, entry) in enumerate(sorted_entries, start=1):
+                nav_orders[original_index] = nav_order
+
+    return nav_orders
+
+
 def build_callable(modules: models.Module, classes: models.Class, config: dict[str, Any], project_root: str):
     doc_root = prepare_doc_space(project_root)
-    nav_order_parent_count: dict[str, int] = {}
+
+    # Pre-compute nav_orders based on sorting rules
+    nav_orders = _compute_nav_orders(config["tree"])
 
     for index, branch in enumerate(config["tree"]):
-        # For nav_order tracking, we need to track by the immediate parent
-        # If there's a grand_parent, the parent is the immediate container
-        # If there's only a parent, that's the immediate container
-        # If neither, it's a top-level item (doesn't need tracking)
-        parent = branch.get("parent")
-        grand_parent = branch.get("grand_parent")
-
-        # Determine nav_order based on hierarchy level
-        if parent or grand_parent:
-            # Child items: track by their immediate parent
-            nav_order_title_tracker = parent
-            if nav_order_title_tracker not in nav_order_parent_count:
-                nav_order_parent_count[nav_order_title_tracker] = 0
-            nav_order_parent_count[nav_order_title_tracker] += 1
-            nav_order = nav_order_parent_count[nav_order_title_tracker]
-        else:
-            # Top-level items: use index-based nav_order
-            nav_order = index + 2
+        nav_order = nav_orders[index]
 
         builder_class = classes.find("import_path=" + branch["builder"]).type
         builder = builder_class(

clearskies_doc_builder/builders/module.py

@@ -9,7 +9,7 @@ from .builder import Builder
 class Module(Builder):
     def __init__(self, branch, modules, classes, doc_root, nav_order):
         super().__init__(branch, modules, classes, doc_root, nav_order)
-        self.class_list = branch["classes"]
+        self.class_list = branch.get("classes", [])
         self.args_to_additional_attributes_map = branch.get("args_to_additional_attributes_map", {})
         self.parent = branch.get("parent", False)
         self.grand_parent = branch.get("grand_parent", False)