feat: show subnamespaces (#36)

* add option show_subnamespaces

* forward config

Author: watermarkhu

docs/usage/configuration/docstrings.md

@@ -611,12 +611,6 @@ plugins:
       show_docstring_namespaces: false
 ```
 
-```tree
-module/
-    __init__.py
-    submodule.py
-```
-
 --8<-- "docs/snippets/+module/module.md"
 
 ???+ preview

docs/usage/configuration/members.md

@@ -549,12 +549,69 @@ plugins:
         ```markdown
         ::: +mymembers
             options:
-              group_by_category: False
+              group_by_category: false
         ```
 
         ::: +mymembers
             options:
-              group_by_category: False
+              group_by_category: false
+
+## `show_subnamespaces`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+
+When rendering a namespace, show its subnamespaces recursively.
+
+This is false by default, because most of the time we render only one namespace per page, and when rendering a full package (a tree of namespaces and their members) on a single page, we quickly run out of [heading levels][heading_level].
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      matlab:
+        options:
+          show_subnamespaces: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: +matlab_namespace
+    options:
+      show_subnamespaces: false
+```
+
+--8<-- "docs/snippets/+module/module.md"
+
+???+ preview
+
+    === "With show subnamespaces"
+        
+        ```markdown
+        ::: +module
+            options:
+              show_subnamespaces: true
+        ```
+
+        ::: +module
+            options:
+              show_subnamespaces: true
+              show_docstring_namespaces: false
+              show_docstring_classes: false
+              show_docstring_functions: false
+
+    === "Without show subnamespaces"
+
+        ```markdown
+        ::: +module
+            options:
+              show_subnamespaces: false
+        ```
+
+        ::: +module
+            options:
+              show_subnamespaces: false
+              show_docstring_namespaces: false
+              show_docstring_classes: false
+              show_docstring_functions: false
 
 ## `summary`
 

src/mkdocstrings_handlers/matlab/collect.py

@@ -238,7 +238,7 @@ def update_model(self, model: MatlabMixin, config: Mapping) -> MatlabMixin:
                     case DocstringSectionKind.parameters:
                         section.title = "Input arguments:"
                     case DocstringSectionKind.returns:
-                        section.title= "Output arguments:"
+                        section.title = "Output arguments:"
                     case DocstringSectionKind.other_parameters:
                         section.title = "Name-Value Arguments:"
 

src/mkdocstrings_handlers/matlab/handler.py

@@ -53,6 +53,7 @@ class MatlabHandler(BaseHandler):
         "members_order": rendering.Order.alphabetical.value,
         "filters": ["!^delete$|^disp$"],
         "group_by_category": True,
+        "show_subnamespaces": False,
         "summary": False,
         "show_labels": True,
         # Docstring options
@@ -120,6 +121,7 @@ class MatlabHandler(BaseHandler):
             The `members` option takes precedence over `filters` (filters will still be applied recursively
             to lower members in the hierarchy). Default: `["!^delete$|^disp$"]`.
         group_by_category (bool): Group the object's children by categories: properties, classes, functions, and namespaces. Default: `True`.
+        show_subnamespaces (bool): When rendering a namespace, show its subnamespaces recursively. Default: `False`.
         summary (bool | dict[str, bool]): Whether to render summaries of namespaces, classes, functions (methods) and properties. Default: `False`.
         show_labels (bool): Whether to show labels of the members. Default: `True`.
 
@@ -251,6 +253,9 @@ def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:
             }
 
         # Map docstring options
+        final_config["show_submodules"] = config.get(
+            "show_subnamespaces", False
+        )
         final_config["show_docstring_attributes"] = config.get(
             "show_docstring_properties", True
         )