Feat/group by category increase granularity

docs/usage/configuration/headings.md

@@ -469,13 +469,17 @@ plugins:
 [](){#option-show_category_heading}
 ## `show_category_heading`
 
-- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+- **:octicons-package-24: Type <code><autoref identifier="bool" optional>bool</autoref> |
+    <autoref identifier="str" optional>str</autoref></code>  :material-equal: `False`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
 When [grouped by categories][group_by_category], show a heading for each category.
 These category headings will appear in the table of contents,
 allowing you to link to them using their permalinks.
 
+`show_category_heading` can be enabled selectively for individual object types by specifying either `mod` or `class`.
+When specified, category headings will only be shown for the chosen type.
+
 WARNING: **Not recommended with deeply nested objects.**
 When injecting documentation for deeply nested objects,
 you'll quickly run out of heading levels, and the objects

src/mkdocstrings_handlers/python/_internal/config.py

@@ -691,10 +691,15 @@ class PythonInputOptions:
     ] = True
 
     show_category_heading: Annotated[
-        bool,
+        Literal["mod", "class", True, False],
         _Field(
             group="headings",
-            description="When grouped by categories, show a heading for each category.",
+            description="""When grouped by categories, show a heading for the categories.
+
+        When true, shows all category headings.
+        When false, shows no category headings.
+        When "mod" or "class", shows only headings on the given object.
+        """,
         ),
     ] = False
 

src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja

@@ -28,12 +28,16 @@ Context:
     {% endif %}
 
     {% if config.group_by_category %}
-
+      
       {% with %}
-
-        {% if config.show_category_heading %}
+        {% if config.show_category_heading is sameas true
+        or (config.show_category_heading == "class" and obj.kind.value == "class")
+        or (config.show_category_heading == "mod" and obj.kind.value == "module")
+        %}
+          {% set show_category_heading = true %}
           {% set extra_level = 1 %}
         {% else %}
+          {% set show_category_heading = false %}
           {% set extra_level = 0 %}
         {% endif %}
 
@@ -44,7 +48,7 @@ Context:
             keep_no_docstrings=config.show_if_no_docstring,
           ) %}
           {% if attributes %}
-            {% if config.show_category_heading %}
+            {% if show_category_heading %}
               {% filter heading(heading_level, id=html_id ~ "-attributes", skip_inventory=config.skip_local_inventory) %}Attributes{% endfilter %}
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
@@ -64,7 +68,7 @@ Context:
             keep_no_docstrings=config.show_if_no_docstring,
           ) %}
           {% if type_aliases %}
-            {% if config.show_category_heading %}
+            {% if show_category_heading %}
               {% filter heading(heading_level, id=html_id ~ "-type_aliases") %}Type Aliases{% endfilter %}
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
@@ -84,7 +88,7 @@ Context:
             keep_no_docstrings=config.show_if_no_docstring,
           ) %}
           {% if classes %}
-            {% if config.show_category_heading %}
+            {% if show_category_heading %}
               {% filter heading(heading_level, id=html_id ~ "-classes", skip_inventory=config.skip_local_inventory) %}Classes{% endfilter %}
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
@@ -104,7 +108,7 @@ Context:
             keep_no_docstrings=config.show_if_no_docstring,
           ) %}
           {% if functions %}
-            {% if config.show_category_heading %}
+            {% if show_category_heading %}
               {% filter heading(heading_level, id=html_id ~ "-functions", skip_inventory=config.skip_local_inventory) %}Functions{% endfilter %}
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
@@ -127,7 +131,7 @@ Context:
               keep_no_docstrings=config.show_if_no_docstring,
             ) %}
             {% if modules %}
-              {% if config.show_category_heading %}
+              {% if show_category_heading %}
                 {% filter heading(heading_level, id=html_id ~ "-modules", skip_inventory=config.skip_local_inventory) %}Modules{% endfilter %}
               {% endif %}
               {% with heading_level = heading_level + extra_level %}