diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index 593b6fb0..8855d60b 100644 --- a/docs/usage/configuration/headings.md +++ b/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 bool | + str :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 diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index 79ba87f9..3d8922d5 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 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..e9d773c2 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja +++ b/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 %}