clear-skies-doc-builder 2.0.7__tar.gz → 2.0.9__tar.gz

{clear_skies_doc_builder-2.0.7 → clear_skies_doc_builder-2.0.9}/CHANGELOG.md

@@ -5,11 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.9] - 2026-01-28
+
+### Added
+- Add ordering
+
+## [2.0.8] - 2026-01-28
+
+### Added
+- Add support for just headings
+
+### Changed
+- Bump version to v2.0.8 by @github-actions[bot]
+
 ## [2.0.7] - 2026-01-28
 
 ### Added
 - Add multi hierarchy
 
+### Changed
+- Bump version to v2.0.7 by @github-actions[bot]
+
 ## [2.0.6] - 2026-01-28
 
 ### Added
@@ -75,6 +91,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * @ made their first contribution
 * @tnijboer made their first contribution in [#1](https://github.com/clearskies-py/doc-builder/pull/1)
 * @cmancone made their first contribution
+[2.0.9]: https://github.com/clearskies-py/doc-builder/compare/v2.0.8..v2.0.9
+[2.0.8]: https://github.com/clearskies-py/doc-builder/compare/v2.0.7..v2.0.8
 [2.0.7]: https://github.com/clearskies-py/doc-builder/compare/v2.0.6..v2.0.7
 [2.0.6]: https://github.com/clearskies-py/doc-builder/compare/v2.0.5..v2.0.6
 [2.0.5]: https://github.com/clearskies-py/doc-builder/compare/v2.0.4..v2.0.5

clear_skies_doc_builder-2.0.9/LATEST_CHANGELOG.md

@@ -0,0 +1,5 @@
+## [2.0.9] - 2026-01-28
+
+### Added
+- Add ordering
+

{clear_skies_doc_builder-2.0.7 → clear_skies_doc_builder-2.0.9}/PKG-INFO

@@ -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 → clear_skies_doc_builder-2.0.9}/README.md

@@ -122,6 +122,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:
@@ -143,3 +175,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 → clear_skies_doc_builder-2.0.9}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "clear-skies-doc-builder"
 description = "The docbuilder for all 'official' clearskies plugins (as well as the main clearskies docs)"
-version = "2.0.7"
+version = "2.0.9"
 license = "MIT"
 readme = "./README.md"
 authors = [{name = "Conor Mancone", email = "cmancone@gmail.com"}]

clear_skies_doc_builder-2.0.9/src/clearskies_doc_builder/build_callable.py

@@ -0,0 +1,107 @@
+from typing import Any
+
+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)
+
+    # Pre-compute nav_orders based on sorting rules
+    nav_orders = _compute_nav_orders(config["tree"])
+
+    for index, branch in enumerate(config["tree"]):
+        nav_order = nav_orders[index]
+
+        builder_class = classes.find("import_path=" + branch["builder"]).type
+        builder = builder_class(
+            branch,
+            modules,
+            classes,
+            doc_root,
+            nav_order=nav_order,
+        )
+        builder.build()

{clear_skies_doc_builder-2.0.7 → clear_skies_doc_builder-2.0.9}/src/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)

{clear_skies_doc_builder-2.0.7 → clear_skies_doc_builder-2.0.9}/uv.lock

@@ -146,7 +146,7 @@ wheels = [
 
 [[package]]
 name = "clear-skies-doc-builder"
-version = "2.0.7"
+version = "2.0.9"
 source = { editable = "." }
 dependencies = [
     { name = "clear-skies" },

clear_skies_doc_builder-2.0.7/LATEST_CHANGELOG.md

@@ -1,5 +0,0 @@
-## [2.0.7] - 2026-01-28
-
-### Added
-- Add multi hierarchy
-

clear_skies_doc_builder-2.0.7/src/clearskies_doc_builder/build_callable.py

@@ -1,39 +0,0 @@
-from typing import Any
-
-from clearskies_doc_builder import models
-from clearskies_doc_builder.prepare_doc_space import prepare_doc_space
-
-
-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] = {}
-
-    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
-
-        builder_class = classes.find("import_path=" + branch["builder"]).type
-        builder = builder_class(
-            branch,
-            modules,
-            classes,
-            doc_root,
-            nav_order=nav_order,
-        )
-        builder.build()