From fd941493839e9050acbea1edf0a3e4b18a7acfe0 Mon Sep 17 00:00:00 2001 From: Iver Noerve Date: Mon, 10 Nov 2025 20:40:04 +0100 Subject: [PATCH 1/6] feat: update show_category_heading with options "mod", "class" --- src/mkdocstrings_handlers/python/_internal/config.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index 79ba87f9..b6664287 100644 --- a/src/mkdocstrings_handlers/python/_internal/config.py +++ b/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 From e1613f2d7a9585afb67339fc7685e14cbb57c23b Mon Sep 17 00:00:00 2001 From: Iver Noerve Date: Mon, 10 Nov 2025 20:41:09 +0100 Subject: [PATCH 2/6] feat: Reflect show_category_heading change in material template --- .../material/_base/children.html.jinja | 24 ++++++++++++------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja index 3be0a33a..556f89ae 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja @@ -28,10 +28,18 @@ 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 %} + {% else %} + {% set show_category_heading = false %} + {% endif %} + + {% if show_category_heading %} {% set extra_level = 1 %} {% else %} {% set extra_level = 0 %} @@ -44,7 +52,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 +72,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 +92,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 +112,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 +135,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 %} From 33abb31eb931fd62faca32a7f37c672c37ba6389 Mon Sep 17 00:00:00 2001 From: Iver Noerve Date: Mon, 10 Nov 2025 20:43:32 +0100 Subject: [PATCH 3/6] style: remove extra whitespace --- src/mkdocstrings_handlers/python/_internal/config.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index b6664287..3d8922d5 100644 --- a/src/mkdocstrings_handlers/python/_internal/config.py +++ b/src/mkdocstrings_handlers/python/_internal/config.py @@ -691,7 +691,7 @@ class PythonInputOptions: ] = True show_category_heading: Annotated[ - Literal["mod", "class", True, False], + Literal["mod", "class", True, False], _Field( group="headings", description="""When grouped by categories, show a heading for the categories. From 8705f23fd6ffde6cfc15af30f86ebfe2c0ae802f Mon Sep 17 00:00:00 2001 From: Iver Noerve Date: Mon, 10 Nov 2025 21:01:44 +0100 Subject: [PATCH 4/6] feat: Update docs to reflect changes. --- docs/usage/configuration/headings.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index 593b6fb0..ebb6cf1b 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -469,13 +469,16 @@ plugins: [](){#option-show_category_heading} ## `show_category_heading` -- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** +- **:octicons-package-24: Type [`str|bool`][] :material-equal: `False`{ title="default value" }** 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 From 0b300b0202d2009351ce465c8a0d46e2ad0c24d4 Mon Sep 17 00:00:00 2001 From: Iver Noerve Date: Mon, 10 Nov 2025 21:37:03 +0100 Subject: [PATCH 5/6] chore: correct doc type definition --- docs/usage/configuration/headings.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index ebb6cf1b..8855d60b 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -469,7 +469,8 @@ plugins: [](){#option-show_category_heading} ## `show_category_heading` -- **:octicons-package-24: Type [`str|bool`][] :material-equal: `False`{ title="default value" }** +- **:octicons-package-24: Type bool | + str :material-equal: `False`{ title="default value" }** When [grouped by categories][group_by_category], show a heading for each category. From 2a76f3090b7941585b7e536784d1ea9da0b7b629 Mon Sep 17 00:00:00 2001 From: Iver Noerve Date: Tue, 11 Nov 2025 09:22:08 +0100 Subject: [PATCH 6/6] chore: Simplify conditionals --- .../python/templates/material/_base/children.html.jinja | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja index 556f89ae..e9d773c2 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja @@ -35,13 +35,9 @@ Context: or (config.show_category_heading == "mod" and obj.kind.value == "module") %} {% set show_category_heading = true %} - {% else %} - {% set show_category_heading = false %} - {% endif %} - - {% if show_category_heading %} {% set extra_level = 1 %} {% else %} + {% set show_category_heading = false %} {% set extra_level = 0 %} {% endif %}