feat: Add heading and toc_label settings

Author: vancromy

docs/usage/configuration/headings.md

@@ -57,6 +57,42 @@ 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 of the object (i.e. the object specfied directly after the identifier `:::`). This will override the default heading generated by the plugin.
+
+!!! warning "Not advised to be used as a general configuration option"
+    This option is not advised to be used as a general 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 general configuration option"
+    This option is not advised to be used as a general 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)
@@ -286,15 +322,15 @@ More text.
     type: preview
 
 //// tab | With ToC entry
-**Table of contents**  
-[Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" }  
-[`object`](#permalink-to-object){ title="#permalink-to-object" }   
-[Other heading](#permalink-to-other-heading){ title="#permalink-to-other-heading" } 
+**Table of contents**
+[Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" }
+[`object`](#permalink-to-object){ title="#permalink-to-object" }
+[Other heading](#permalink-to-other-heading){ title="#permalink-to-other-heading" }
 ////
 
 //// tab | Without ToC entry
-**Table of contents**  
-[Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" }  
+**Table of contents**
+[Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" }
 [Other heading](#permalink-to-other-heading){ title="#permalink-to-other-heading" }
 ////
 ///
@@ -400,7 +436,7 @@ plugins:
 Show the full Python path of every object.
 
 Same as for [`show_root_members_full_path`][],
-but for every member, recursively. This option takes precedence over 
+but for every member, recursively. This option takes precedence over
 [`show_root_members_full_path`][]:
 
 `show_root_members_full_path` | `show_object_full_path` | Direct root members path
@@ -454,7 +490,7 @@ When [grouped by categories][group_by_category], show a heading for each categor
 These category headings will appear in the table of contents,
 allowing you to link to them using their permalinks.
 
-WARNING: **Not recommended with deeply nested object**  
+WARNING: **Not recommended with deeply nested object**
 When injecting documentation for deeply nested objects,
 you'll quickly run out of heading levels, and the objects
 at the bottom of the tree risk all getting documented

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",
@@ -141,6 +143,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

@@ -12,7 +12,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering " + attribute.path) }}
@@ -44,12 +44,12 @@ Context:
 
         {% block heading scoped %}
           {#- Heading block.
-          
+
           This block renders the heading for the attribute.
           -#}
           {% 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 %}
@@ -60,7 +60,7 @@ Context:
 
         {% block labels scoped %}
           {#- Labels block.
-          
+
           This block renders the labels for the attribute.
           -#}
           {% with labels = attribute.labels %}
@@ -72,7 +72,7 @@ Context:
 
       {% block signature scoped %}
         {#- Signature block.
-        
+
         This block renders the signature for the attribute.
         -#}
         {% if config.separate_signature %}
@@ -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 %}
@@ -99,14 +99,14 @@ Context:
     <div class="doc doc-contents {% if root %}first{% endif %}">
       {% block contents scoped %}
         {#- Contents block.
-        
+
         This block renders the contents of the attribute.
         It contains other blocks that users can override.
         Overriding the contents block allows to rearrange the order of the blocks.
         -#}
         {% block docstring scoped %}
           {#- Docstring block.
-          
+
           This block renders the docstring for the attribute.
           -#}
           {% with docstring_sections = attribute.docstring.parsed %}

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

@@ -11,7 +11,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering " + class.path) }}
@@ -43,12 +43,12 @@ Context:
 
         {% block heading scoped %}
           {#- Heading block.
-          
+
           This block renders the heading for the class.
           -#}
           {% 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) %}
@@ -62,7 +62,7 @@ Context:
 
         {% block labels scoped %}
           {#- Labels block.
-          
+
           This block renders the labels for the class.
           -#}
           {% with labels = class.labels %}
@@ -74,7 +74,7 @@ Context:
 
       {% block signature scoped %}
         {#- Signature block.
-        
+
         This block renders the signature for the class.
         Overloads of the `__init__` method are rendered if `merge_init_into_class` is enabled.
         The actual `__init__` method signature is only rendered if `separate_signature` is also enabled.
@@ -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 %}
@@ -117,14 +117,14 @@ Context:
     <div class="doc doc-contents {% if root %}first{% endif %}">
       {% block contents scoped %}
         {#- Contents block.
-        
+
         This block renders the contents of the class.
         It contains other blocks that users can override.
         Overriding the contents block allows to rearrange the order of the blocks.
         -#}
         {% block bases scoped %}
           {#- Class bases block.
-          
+
           This block renders the bases for the class.
           -#}
           {% if config.show_bases and class.bases %}
@@ -138,7 +138,7 @@ Context:
 
         {% block docstring scoped %}
           {#- Docstring block.
-          
+
           This block renders the docstring for the class.
           -#}
           {% with docstring_sections = class.docstring.parsed %}
@@ -161,15 +161,15 @@ Context:
 
         {% block summary scoped %}
           {#- Summary block.
-          
+
           This block renders auto-summaries for classes, methods, and attributes.
           -#}
           {% include "summary"|get_template with context %}
         {% endblock summary %}
 
         {% block source scoped %}
           {#- Source block.
-          
+
           This block renders the source code for the class.
           -#}
           {% if config.show_source %}
@@ -205,7 +205,7 @@ Context:
 
         {% block children scoped %}
           {#- Children block.
-          
+
           This block renders the children (members) of the class.
           -#}
           {% set root = False %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja

@@ -9,7 +9,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering parameters section") }}

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

@@ -11,7 +11,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering " + function.path) }}
@@ -49,12 +49,12 @@ Context:
 
         {% block heading scoped %}
           {#- Heading block.
-          
+
           This block renders the heading for the function.
           -#}
           {% 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 %}
@@ -64,7 +64,7 @@ Context:
 
         {% block labels scoped %}
           {#- Labels block.
-          
+
           This block renders the labels for the function.
           -#}
           {% with labels = function.labels %}
@@ -76,7 +76,7 @@ Context:
 
       {% block signature scoped %}
         {#- Signature block.
-        
+
         This block renders the signature for the function,
         as well as its overloaded signatures if any.
         -#}
@@ -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 %}
@@ -114,14 +114,14 @@ Context:
     <div class="doc doc-contents {% if root %}first{% endif %}">
       {% block contents scoped %}
         {#- Contents block.
-        
+
         This block renders the contents of the function.
         It contains other blocks that users can override.
         Overriding the contents block allows to rearrange the order of the blocks.
         -#}
         {% block docstring scoped %}
           {#- Docstring block.
-          
+
           This block renders the docstring for the function.
           -#}
           {% with docstring_sections = function.docstring.parsed %}
@@ -131,7 +131,7 @@ Context:
 
         {% block source scoped %}
           {#- Source block.
-          
+
           This block renders the source code for the function.
           -#}
           {% if config.show_source and function.source %}