feat: Add heading and toc_label options

Issue-mkdocstrings-725: mkdocstrings/mkdocstrings#725
PR-236: #236

Author: vancromy

docs/usage/configuration/headings.md

@@ -57,6 +57,39 @@ plugins:
 ////
 ///
 
+## `heading`
+
+- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier `:::`). This will override the default heading generated by the plugin.
+
+WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.
+
+```md title="in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      heading: "My fancy module"
+```
+
+## `toc_label`
+
+- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier `:::`). This will override the default label generated by the plugin.
+
+WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object.
+
+NOTE: **Use with/without `heading`.** If you use this option without specifying a custom `heading`, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for `heading` and `toc_label`, we leave the customization entirely up to you.
+
+```md title="in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      heading: "My fancy module"
+      toc_label: "My fancy module"
+```
+
 ## `parameter_headings`
 
 [:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0)

src/mkdocstrings_handlers/python/handler.py

@@ -107,6 +107,8 @@ class PythonHandler(BaseHandler):
         "show_inheritance_diagram": False,
         "show_submodules": False,
         "group_by_category": True,
+        "heading": "",
+        "toc_label": "",
         "heading_level": 2,
         "members_order": rendering.Order.alphabetical.value,
         "docstring_section_style": "table",
@@ -143,6 +145,8 @@ class PythonHandler(BaseHandler):
             The modules must be listed as an array of strings. Default: `None`.
 
     Attributes: Headings options:
+        heading (str): A custom string to override the autogenerated heading of the root object.
+        toc_label (str): A custom string to override the autogenerated toc label of the root object.
         heading_level (int): The initial heading level to use. Default: `2`.
         parameter_headings (bool): Whether to render headings for parameters (therefore showing parameters in the ToC). Default: `False`.
         show_root_heading (bool): Show the heading of the object at the root of the documentation tree

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

@@ -49,7 +49,7 @@ Context:
           -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
           {% if config.separate_signature %}
-            <span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
+            <span class="doc doc-object-name doc-attribute-name">{{ config.heading if config.heading and root else attribute_name }}</span>
           {% else %}
             {%+ filter highlight(language="python", inline=True) %}
               {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %}
@@ -88,7 +88,7 @@ Context:
         {% filter heading(heading_level,
             role="data" if attribute.parent.kind.value == "module" else "attr",
             id=html_id,
-            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + attribute.name,
+            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute_name),
             hidden=True,
           ) %}
         {% endfilter %}

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

@@ -48,7 +48,7 @@ Context:
           -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>{% endif %}
           {% if config.separate_signature %}
-            <span class="doc doc-object-name doc-class-name">{{ class_name }}</span>
+            <span class="doc doc-object-name doc-class-name">{{ config.heading if config.heading and root else class_name }}</span>
           {% elif config.merge_init_into_class and "__init__" in all_members %}
             {% with function = all_members["__init__"] %}
               {%+ filter highlight(language="python", inline=True) %}
@@ -106,7 +106,7 @@ Context:
         {% filter heading(heading_level,
             role="class",
             id=html_id,
-            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + class.name,
+            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else class.name),
             hidden=True,
           ) %}
         {% endfilter %}

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

@@ -54,7 +54,7 @@ Context:
           -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-{{ symbol_type }}"></code>{% endif %}
           {% if config.separate_signature %}
-            <span class="doc doc-object-name doc-function-name">{{ function_name }}</span>
+            <span class="doc doc-object-name doc-function-name">{{ config.heading if config.heading and root else function_name }}</span>
           {% else %}
             {%+ filter highlight(language="python", inline=True) %}
               {{ function_name }}{% include "signature"|get_template with context %}
@@ -103,7 +103,7 @@ Context:
             heading_level,
             role="function",
             id=html_id,
-            toc_label=(('<code class="doc-symbol doc-symbol-toc doc-symbol-' + symbol_type + '"></code>&nbsp;')|safe if config.show_symbol_type_toc else '') + function.name,
+            toc_label=(('<code class="doc-symbol doc-symbol-toc doc-symbol-' + symbol_type + '"></code>&nbsp;')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name),
             hidden=True,
           ) %}
         {% endfilter %}

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

@@ -38,7 +38,7 @@ Context:
           role="module",
           id=html_id,
           class="doc doc-heading",
-          toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + module.name,
+          toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name),
         ) %}
 
         {% block heading scoped %}
@@ -48,7 +48,7 @@ Context:
           -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-module"></code>{% endif %}
           {% if config.separate_signature %}
-            <span class="doc doc-object-name doc-module-name">{{ module_name }}</span>
+            <span class="doc doc-object-name doc-module-name">{{ config.heading if config.heading and root else module_name }}</span>
           {% else %}
             <code>{{ module_name }}</code>
           {% endif %}
@@ -71,7 +71,7 @@ Context:
         {% filter heading(heading_level,
             role="module",
             id=html_id,
-            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + module.name,
+            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name),
             hidden=True,
           ) %}
         {% endfilter %}