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

clear_skies_doc_builder-2.0.7.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: clear-skies-doc-builder
+Version: 2.0.7
+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
+Project-URL: changelog, https://github.com/clearskies-py/docs/blob/main/CHANGELOG.md
+Author-email: Conor Mancone <cmancone@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <4.0,>=3.11
+Requires-Dist: clear-skies<3.0.0,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: types-requests>=2.32.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# docs
+
+The documentation builder for clearskies and related plugins
+
+## Overview
+
+Each "official" clearskies module (including the core clearskies library itself) has the documentation primarily written in the codebase as docblocks.  The documentation site is then built by extracting these docblocks and stitching them together.  To be clear, this isn't about the low-level "API" documentation that describes every single class/method in the framework.  Rather, this is about the primary documentation site itself (clearskies.info) which is focused on high-level use cases and examples of the primary configuration options.  As a result, it's not a simple matter of just iterating over the classes/methods and building documentation.  To build a coherent documentation site, each plugin has a configuration file that basically outlines the final "structure" or organization of the resulting documentation, as well as the name of a builder class that will combine that configuration information with the codebase itself to create the actual docs.
+
+The docs themselves (in the source code) are all written with markdown.  This documentation builder then takes that markdwon and adds the necessary headers/etc so to make them valid files for [Jekyll](https://jekyllrb.com/), the builder for the current documentation site.  The site itself is hosted in S3, so building an actual documentation site means:
+
+ 1. Properly documenting everything inside of the source code via markdown.
+ 2. Creating a config file (`docs/python/config.json`) to map source code docs to Jekyll files.
+ 3. Creating a skeleton of a Jekyll site in the `doc/jekyll` folder of the plugin.
+ 4. Installing this doc builder via `poetry add clear-skies-doc-builder`.
+ 5. Run the doc builder.
+ 6. Build with Jekyll.
+ 7. Push to the appropriate subfolder via S3.
+ 8. (Only once) Update the main clearskies doc site to know about the new subfolder for this plugin.
+
+Of course, we want the Jekyll sites to be consistent with eachother in terms of style/look.  In the long run we'll probably have this doc builder also bootstrap the Jekyll site, but for now you just have to manually setup the Jekyll build using the main clearskies repo as a template.
+
+## Configuration File Structure
+
+The `config.json` file defines the documentation structure using a tree of entries. Each entry specifies a documentation section with its source class and builder.
+
+### Basic Structure
+
+```json
+{
+  "tree": [
+    {
+      "title": "Section Title",
+      "source": "package.module.ClassName",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "classes": ["package.module.Class1", "package.module.Class2"]
+    }
+  ]
+}
+```
+
+### Nested Hierarchy (Parent/Grand-Parent)
+
+The doc builder supports up to 3 levels of navigation hierarchy using `parent` and `grand_parent` fields. This is useful for organizing documentation of submodules under a common heading.
+
+#### Two-Level Hierarchy (Parent) - Module with Classes
+
+Use this when you want to document a submodule's classes under a parent section:
+
+```json
+{
+  "tree": [
+    {
+      "title": "Cursors",
+      "source": "clearskies.cursors.Cursor",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "classes": [
+        "clearskies.cursors.MemoryCursor",
+        "clearskies.cursors.FileCursor"
+      ]
+    },
+    {
+      "title": "From Environment",
+      "source": "clearskies.cursors.from_environment.FromEnvironmentBase",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "parent": "Cursors",
+      "classes": [
+        "clearskies.cursors.from_environment.EnvCursor",
+        "clearskies.cursors.from_environment.SecretsCursor"
+      ]
+    }
+  ]
+}
+```
+
+This creates:
+- `docs/cursors/index.md` - Parent section with overview
+- `docs/cursors/memory-cursor.md` - Class documentation
+- `docs/cursors/file-cursor.md` - Class documentation
+- `docs/cursors/from-environment/index.md` - Submodule section with `parent: Cursors`
+- `docs/cursors/from-environment/env-cursor.md` - Class with `parent: From Environment`
+- `docs/cursors/from-environment/secrets-cursor.md` - Class with `parent: From Environment`
+
+#### Three-Level Hierarchy (Grand-Parent)
+
+For deeper nesting, use `grand_parent` to create a third level:
+
+```json
+{
+  "tree": [
+    {
+      "title": "Cursors",
+      "source": "clearskies.cursors.Cursor",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "classes": ["clearskies.cursors.MemoryCursor"]
+    },
+    {
+      "title": "From Environment",
+      "source": "clearskies.cursors.from_environment.FromEnvironmentBase",
+      "builder": "clearskies_doc_builder.builders.SingleClass",
+      "parent": "Cursors"
+    },
+    {
+      "title": "AWS Secrets",
+      "source": "clearskies.cursors.from_environment.aws.AWSSecretsBase",
+      "builder": "clearskies_doc_builder.builders.Module",
+      "parent": "From Environment",
+      "grand_parent": "Cursors",
+      "classes": [
+        "clearskies.cursors.from_environment.aws.SecretsManagerCursor",
+        "clearskies.cursors.from_environment.aws.ParameterStoreCursor"
+      ]
+    }
+  ]
+}
+```
+
+This creates:
+- `docs/cursors/index.md` - Grand-parent section
+- `docs/cursors/from-environment/index.md` - Parent section with `parent: Cursors`
+- `docs/cursors/from-environment/aws-secrets/index.md` - Child section with `parent: From Environment` and `grand_parent: Cursors`
+- `docs/cursors/from-environment/aws-secrets/secrets-manager-cursor.md` - Class documentation
+
+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.
+
+#### Using SingleClass for Individual Classes
+
+You can also use `SingleClass` builder for documenting individual classes within a hierarchy:
+
+```json
+{
+  "tree": [
+    {
+      "title": "Cursors",
+      "source": "clearskies.cursors.Cursor",
+      "builder": "clearskies_doc_builder.builders.SingleClass"
+    },
+    {
+      "title": "Environment Cursor",
+      "source": "clearskies.cursors.from_environment.EnvironmentCursor",
+      "builder": "clearskies_doc_builder.builders.SingleClass",
+      "parent": "Cursors"
+    }
+  ]
+}
+```

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

@@ -1,15 +1,15 @@
 clearskies_doc_builder/__init__.py,sha256=AFQzZ9HwIxPyLpsUhkSDRh_6hm8-5H4RpAelTShCDTc,1300
-clearskies_doc_builder/build_callable.py,sha256=9_HrytRA5MeGpuUKRFgmlK5Mb1WKt6TfWlCOi1aS-Pc,983
+clearskies_doc_builder/build_callable.py,sha256=sCjXSnqFU-27zr2-i5D5I3M0ebDWO4OEvikvSNQg6oA,1608
 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=0vlnREe3TcYjrmBFvAlTFeWzQ-LzT__wVJG7inWQLzM,3581
-clearskies_doc_builder/backends/class_backend.py,sha256=6jOKzUDLYIQofCxno3Y9L_FiKT9x2MsPOe3c1HJ2k2M,4031
-clearskies_doc_builder/backends/module_backend.py,sha256=hJMeJtgInaZfXnFpxtCuRA05jBZTpMhVrR8Se3uul9Y,5718
+clearskies_doc_builder/backends/attribute_backend.py,sha256=2nivmJpedPsoQibf9NlIT-Wfvg0PbfHKoT06xKkt0O0,3634
+clearskies_doc_builder/backends/class_backend.py,sha256=JIKRYAVFxYEOHV7tG9RBrfuo1SN8Uw4KKaMz5YzlMHo,4112
+clearskies_doc_builder/backends/module_backend.py,sha256=hHJXt00TJIF3-69p_kjdAZuWOyGhpCvD3TgOKMOp4og,5971
 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=3aQ_UTKJFDDUCNHKhwn1sr74CKR3YCe7xuWRX528eAw,6133
-clearskies_doc_builder/builders/module.py,sha256=occ49CTmX9imWK1zNHf0JAQLB46lc2mm2vnZieP-rhg,3287
-clearskies_doc_builder/builders/single_class.py,sha256=3JZBVtt9GToPFoSIlggWbalRFbfayLpLVb9-2-1ymdY,3454
+clearskies_doc_builder/builders/builder.py,sha256=2QZDscwOZ4vfx4NzFU4AyKgAPuKVU0jsYBcT42CZgzY,7957
+clearskies_doc_builder/builders/module.py,sha256=WlLSMPN3AoCaMg66DxvRXiO3x4zVFhoYGXjHM6U0M6c,4912
+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
 clearskies_doc_builder/columns/any.py,sha256=5kjwEz4-t7MH9sFyycWxEcDdDmKZsb3wfX1Nmvc6QI4,998
@@ -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.5.dist-info/METADATA,sha256=tePfhHwlEy6SMHEOOb4dfRQFk-l4ZfUQT-ww_X89meQ,3075
-clear_skies_doc_builder-2.0.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-clear_skies_doc_builder-2.0.5.dist-info/licenses/LICENSE,sha256=pgH32-xrgpIDf6WIBUA1X19o-sIHIXgToCxo-tBWDdw,1071
-clear_skies_doc_builder-2.0.5.dist-info/RECORD,,
+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.5.dist-info → clear_skies_doc_builder-2.0.7.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

clearskies_doc_builder/backends/attribute_backend.py

@@ -5,6 +5,7 @@ import clearskies
 import clearskies.column
 import clearskies.model
 import clearskies.query
+from clearskies.query.result import RecordsQueryResult
 
 from clearskies_doc_builder.backends.module_backend import ModuleBackend
 
@@ -18,7 +19,7 @@ class AttributeBackend(ModuleBackend):
 
     def records(
         self, query: clearskies.query.Query, next_page_data: dict[str, str | int] | None = None
-    ) -> list[dict[str, Any]]:
+    ) -> RecordsQueryResult:
         """
         Return a list of records that match the given query configuration.
 

clearskies_doc_builder/backends/class_backend.py

@@ -7,6 +7,7 @@ import clearskies
 import clearskies.column
 import clearskies.model
 import clearskies.query
+from clearskies.query.result import RecordsQueryResult
 
 from clearskies_doc_builder.backends.module_backend import ModuleBackend
 
@@ -19,7 +20,7 @@ class ClassBackend(ModuleBackend):
 
     def records(
         self, query: clearskies.query.Query, next_page_data: dict[str, str | int] | None = None
-    ) -> list[dict[str, Any]]:
+    ) -> RecordsQueryResult:
         """
         Return a list of records that match the given query configuration.
 
@@ -53,7 +54,7 @@ class ClassBackend(ModuleBackend):
                 raise ValueError(
                     f"I was asked to import the class named '{import_path}' but this doesn't actually reference a class"
                 )
-            return [self.unpack(Class, module)]
+            return RecordsQueryResult(records=[self.unpack(Class, module)])
 
         if "module" not in query.conditions_by_column:
             raise ValueError(

clearskies_doc_builder/backends/module_backend.py

@@ -9,6 +9,7 @@ import clearskies.model
 import clearskies.query
 from clearskies.autodoc.schema import Integer as AutoDocInteger
 from clearskies.autodoc.schema import Schema as AutoDocSchema
+from clearskies.query.result import CountQueryResult, RecordQueryResult, RecordsQueryResult, SuccessQueryResult
 
 
 class ModuleBackend(clearskies.backends.Backend):
@@ -19,25 +20,25 @@ class ModuleBackend(clearskies.backends.Backend):
         "module": lambda module, value: id(module) == id(value),
     }
 
-    def update(self, id: int | str, data: dict[str, Any], model: clearskies.model.Model) -> dict[str, Any]:
+    def update(self, id: int | str, data: dict[str, Any], model: clearskies.model.Model) -> RecordQueryResult:
         """Update the record with the given id with the information from the data dictionary."""
         raise Exception(f"The {self.__class__.__name__} only supports read operations: update is not allowed")
 
-    def create(self, data: dict[str, Any], model: clearskies.model.Model) -> dict[str, Any]:
+    def create(self, data: dict[str, Any], model: clearskies.model.Model) -> RecordQueryResult:
         """Create a record with the information from the data dictionary."""
         raise Exception(f"The {self.__class__.__name__} only supports read operations: create is not allowed")
 
-    def delete(self, id: int | str, model: clearskies.model.Model) -> bool:
+    def delete(self, id: int | str, model: clearskies.model.Model) -> SuccessQueryResult:
         """Delete the record with the given id."""
         raise Exception(f"The {self.__class__.__name__} only supports read operations: delete is not allowed")
 
-    def count(self, query: clearskies.query.Query) -> int:
+    def count(self, query: clearskies.query.Query) -> CountQueryResult:
         """Return the number of records which match the given query configuration."""
-        return len(self.records(query))
+        return CountQueryResult(count=len(self.records(query).records))
 
     def records(
         self, query: clearskies.query.Query, next_page_data: dict[str, str | int] | None = None
-    ) -> list[dict[str, Any]]:
+    ) -> RecordsQueryResult:
         """
         Return a list of records that match the given query configuration.
 
@@ -58,7 +59,7 @@ class ModuleBackend(clearskies.backends.Backend):
         if module_name_condition:
             module_name = module_name_condition[0].values[0]
             module = importlib.import_module(module_name)
-            return [self.unpack(module)]
+            return RecordsQueryResult(records=[self.unpack(module)])
 
         matching_modules = []
         module_names = set(sys.modules) & set(globals())
@@ -92,8 +93,8 @@ class ModuleBackend(clearskies.backends.Backend):
             "module": module,
         }
 
-    def paginate(self, records, query):
-        return records
+    def paginate(self, records, query) -> RecordsQueryResult:
+        return RecordsQueryResult(records=records)
 
     def validate_pagination_data(self, data: dict[str, Any], case_mapping: Callable) -> str:
         extra_keys = set(data.keys()) - set(self.allowed_pagination_keys())

clearskies_doc_builder/build_callable.py

@@ -6,19 +6,34 @@ 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 = {}
+    nav_order_parent_count: dict[str, int] = {}
 
     for index, branch in enumerate(config["tree"]):
-        nav_order_title_tracker = branch.get("parent", branch["title"])
-        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
+        # 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_parent_count[nav_order_title_tracker] if branch.get("parent") else index + 2,
+            nav_order=nav_order,
         )
         builder.build()

clearskies_doc_builder/builders/builder.py

@@ -30,6 +30,40 @@ class Builder:
         with output_file.open(mode="w") as doc_file:
             doc_file.write(doc)
 
+    def make_index_from_class_overview_with_hierarchy(
+        self, title_snake_case, source_class, section_folder_path, section_name, parent=None, grand_parent=None
+    ):
+        """
+        Create an index file for a module section with support for nested hierarchy.
+
+        This method creates the index.md file for a module section, supporting up to 3 levels
+        of navigation hierarchy (grand_parent -> parent -> current).
+
+        Args:
+            title_snake_case: The snake-case version of the title for the filename
+            source_class: The source class to extract documentation from
+            section_folder_path: Path to the section folder
+            section_name: The section name for permalink generation
+            parent: Optional parent title for 2-level hierarchy
+            grand_parent: Optional grand_parent title for 3-level hierarchy
+        """
+        filename = "index"
+        section_folder_path.mkdir(parents=True, exist_ok=True)
+
+        # Use instance attributes if not provided as arguments
+        parent = parent if parent is not None else getattr(self, "parent", None)
+        grand_parent = grand_parent if grand_parent is not None else getattr(self, "grand_parent", None)
+
+        doc = self.build_header(self.title, filename, section_name, parent, self.nav_order, True, grand_parent)
+        (elevator_pitch, overview) = self.parse_overview_doc(
+            self.raw_docblock_to_md(source_class.doc).lstrip("\n").lstrip(" ")
+        )
+        doc += f"\n\n# {self.title}\n\n{elevator_pitch}\n\n## Overview\n\n{overview}"
+
+        output_file = section_folder_path / f"{filename}.md"
+        with output_file.open(mode="w") as doc_file:
+            doc_file.write(doc)
+
     def parse_overview_doc(self, overview_doc):
         parts = overview_doc.lstrip("\n").split("\n", 1)
         if len(parts) < 2:
@@ -105,7 +139,7 @@ class Builder:
         self._attribute_cache[source_class.source_file] = doc_strings
         return doc_strings
 
-    def build_header(self, title, filename, section_name, parent, nav_order, has_children):
+    def build_header(self, title, filename, section_name, parent, nav_order, has_children, grand_parent=None):
         permalink = "/docs/" + (f"{section_name}/" if section_name else "") + f"{filename}.html"
         header = f"""---
 layout: default
@@ -113,6 +147,8 @@ title: {title}
 permalink: {permalink}
 nav_order: {nav_order}
 """
+        if grand_parent:
+            header += f"grand_parent: {grand_parent}\n"
         if parent:
             header += f"parent: {parent}\n"
         if has_children:

clearskies_doc_builder/builders/module.py

@@ -11,14 +11,43 @@ class Module(Builder):
         super().__init__(branch, modules, classes, doc_root, nav_order)
         self.class_list = branch["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)
 
     def build(self):
         title_snake_case = clearskies.functional.string.title_case_to_snake_case(self.title.replace(" ", "")).replace(
             "_", "-"
         )
-        section_folder_path = self.doc_root / title_snake_case
+
+        # Determine the section folder path based on hierarchy
+        if self.grand_parent:
+            # Three-level hierarchy: grand_parent/parent/title/
+            grand_parent_snake = (
+                clearskies.functional.string.title_case_to_snake_case(self.grand_parent)
+                .replace("_", "-")
+                .replace(" ", "")
+            )
+            parent_snake = (
+                clearskies.functional.string.title_case_to_snake_case(self.parent).replace("_", "-").replace(" ", "")
+            )
+            section_name = f"{grand_parent_snake}/{parent_snake}/{title_snake_case}"
+            section_folder_path = self.doc_root / grand_parent_snake / parent_snake / title_snake_case
+        elif self.parent:
+            # Two-level hierarchy: parent/title/
+            parent_snake = (
+                clearskies.functional.string.title_case_to_snake_case(self.parent).replace("_", "-").replace(" ", "")
+            )
+            section_name = f"{parent_snake}/{title_snake_case}"
+            section_folder_path = self.doc_root / parent_snake / title_snake_case
+        else:
+            # Top-level: title/
+            section_name = title_snake_case
+            section_folder_path = self.doc_root / title_snake_case
+
         source_class = self.classes.find(f"import_path={self.source}")
-        self.make_index_from_class_overview(title_snake_case, source_class, section_folder_path)
+        self.make_index_from_class_overview_with_hierarchy(
+            title_snake_case, source_class, section_folder_path, section_name
+        )
 
         default_args = self.default_args()
 
@@ -28,7 +57,12 @@ class Module(Builder):
             source_class = self.classes.find(f"import_path={class_name}")
             title = source_class.name
             filename = clearskies.functional.string.title_case_to_snake_case(source_class.name).replace("_", "-")
-            class_doc = self.build_header(source_class.name, filename, title_snake_case, self.title, nav_order, False)
+            # For classes within a module, the module title becomes the parent
+            # and if the module has a parent, that becomes the grand_parent
+            class_grand_parent = self.parent if self.parent else None
+            class_doc = self.build_header(
+                source_class.name, filename, section_name, self.title, nav_order, False, class_grand_parent
+            )
             (elevator_pitch, overview) = self.parse_overview_doc(
                 self.raw_docblock_to_md(source_class.doc).lstrip("\n").lstrip(" ")
             )

clearskies_doc_builder/builders/single_class.py

@@ -12,21 +12,44 @@ class SingleClass(Builder):
         self.additional_attribute_sources = branch.get("additional_attribute_sources", [])
         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)
 
     def build(self):
-        section_name = (
-            clearskies.functional.string.title_case_to_snake_case(self.parent if self.parent else self.title)
-            .replace("_", "-")
-            .replace(" ", "")
-        )
-        section_folder_path = self.doc_root / section_name
-        section_folder_path.mkdir(exist_ok=True)
+        # Determine the section folder path based on hierarchy
+        if self.grand_parent:
+            # Three-level hierarchy: grand_parent/parent/file.md
+            grand_parent_snake = (
+                clearskies.functional.string.title_case_to_snake_case(self.grand_parent)
+                .replace("_", "-")
+                .replace(" ", "")
+            )
+            parent_snake = (
+                clearskies.functional.string.title_case_to_snake_case(self.parent).replace("_", "-").replace(" ", "")
+            )
+            section_name = f"{grand_parent_snake}/{parent_snake}"
+            section_folder_path = self.doc_root / grand_parent_snake / parent_snake
+        elif self.parent:
+            # Two-level hierarchy: parent/file.md
+            section_name = (
+                clearskies.functional.string.title_case_to_snake_case(self.parent).replace("_", "-").replace(" ", "")
+            )
+            section_folder_path = self.doc_root / section_name
+        else:
+            # Top-level: title/index.md
+            section_name = (
+                clearskies.functional.string.title_case_to_snake_case(self.title).replace("_", "-").replace(" ", "")
+            )
+            section_folder_path = self.doc_root / section_name
+
+        section_folder_path.mkdir(parents=True, exist_ok=True)
         source_class = self.classes.find(f"import_path={self.source}")
 
         title_snake_case = clearskies.functional.string.title_case_to_snake_case(self.title.replace(" ", "")).replace(
             "_", "-"
         )
-        class_doc = self.build_header(self.title, title_snake_case, section_name, self.parent, self.nav_order, False)
+        class_doc = self.build_header(
+            self.title, title_snake_case, section_name, self.parent, self.nav_order, False, self.grand_parent
+        )
         (elevator_pitch, overview) = self.parse_overview_doc(
             self.raw_docblock_to_md(source_class.doc).lstrip("\n").lstrip(" ")
         )
@@ -70,10 +93,17 @@ class SingleClass(Builder):
 
         class_doc += f"{table_of_contents}\n{main_doc}"
 
-        output_file = section_folder_path / (
-            "index.md"
-            if not self.parent
-            else clearskies.functional.string.title_case_to_snake_case(self.title.replace(" ", "")) + ".md"
-        )
+        # Determine output filename based on hierarchy level
+        if self.parent or self.grand_parent:
+            # Child or grandchild: use title as filename
+            output_filename = (
+                clearskies.functional.string.title_case_to_snake_case(self.title.replace(" ", "")).replace("_", "-")
+                + ".md"
+            )
+        else:
+            # Top-level: use index.md
+            output_filename = "index.md"
+
+        output_file = section_folder_path / output_filename
         with output_file.open(mode="w") as doc_file:
             doc_file.write(class_doc)

clear_skies_doc_builder-2.0.5.dist-info/METADATA

@@ -1,40 +0,0 @@
-Metadata-Version: 2.4
-Name: clear-skies-doc-builder
-Version: 2.0.5
-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
-Project-URL: changelog, https://github.com/clearskies-py/docs/blob/main/CHANGELOG.md
-Author-email: Conor Mancone <cmancone@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Requires-Python: <4.0,>=3.11
-Requires-Dist: clear-skies<3.0.0,>=2.0.0
-Provides-Extra: dev
-Requires-Dist: types-requests>=2.32.4; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# docs
-
-The documentation builder for clearskies and related plugins
-
-## Overview
-
-Each "official" clearskies module (including the core clearskies library itself) has the documentation primarily written in the codebase as docblocks.  The documentation site is then built by extracting these docblocks and stitching them together.  To be clear, this isn't about the low-level "API" documentation that describes every single class/method in the framework.  Rather, this is about the primary documentation site itself (clearskies.info) which is focused on high-level use cases and examples of the primary configuration options.  As a result, it's not a simple matter of just iterating over the classes/methods and building documentation.  To build a coherent documentation site, each plugin has a configuration file that basically outlines the final "structure" or organization of the resulting documentation, as well as the name of a builder class that will combine that configuration information with the codebase itself to create the actual docs.
-
-The docs themselves (in the source code) are all written with markdown.  This documentation builder then takes that markdwon and adds the necessary headers/etc so to make them valid files for [Jekyll](https://jekyllrb.com/), the builder for the current documentation site.  The site itself is hosted in S3, so building an actual documentation site means:
-
- 1. Properly documenting everything inside of the source code via markdown.
- 2. Creating a config file (`docs/python/config.json`) to map source code docs to Jekyll files.
- 3. Creating a skeleton of a Jekyll site in the `doc/jekyll` folder of the plugin.
- 4. Installing this doc builder via `poetry add clear-skies-doc-builder`.
- 5. Run the doc builder.
- 6. Build with Jekyll.
- 7. Push to the appropriate subfolder via S3.
- 8. (Only once) Update the main clearskies doc site to know about the new subfolder for this plugin.
-
-Of course, we want the Jekyll sites to be consistent with eachother in terms of style/look.  In the long run we'll probably have this doc builder also bootstrap the Jekyll site, but for now you just have to manually setup the Jekyll build using the main clearskies repo as a template.