{% 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 %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
index ff5e51c9..aefa98d1 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
+++ b/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 %}
{% 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=('
'|safe if config.show_symbol_type_toc else '') + class.name,
+ toc_label=('
'|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:
{% 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,7 +161,7 @@ Context:
{% block summary scoped %}
{#- Summary block.
-
+
This block renders auto-summaries for classes, methods, and attributes.
-#}
{% include "summary"|get_template with context %}
@@ -169,7 +169,7 @@ Context:
{% 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 %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja
index fef553b1..d4e9acb8 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja
+++ b/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") }}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
index 973c762e..5e803ffb 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
+++ b/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 %}
{% endif %}
{% if config.separate_signature %}
-
{{ function_name }}
+
{{ config.heading if config.heading and root else function_name }}
{% 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=(('
')|safe if config.show_symbol_type_toc else '') + function.name,
+ toc_label=(('
')|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:
{% 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 %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
index 2085b95d..fa2d2e6a 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.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 " + module.path) }}
@@ -38,17 +38,17 @@ Context:
role="module",
id=html_id,
class="doc doc-heading",
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + module.name,
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name),
) %}
{% block heading scoped %}
{#- Heading block.
-
+
This block renders the heading for the module.
-#}
{% if config.show_symbol_type_heading %}
{% endif %}
{% if config.separate_signature %}
-
{{ module_name }}
+
{{ config.heading if config.heading and root else module_name }}
{% else %}
{{ module_name }}
{% endif %}
@@ -56,7 +56,7 @@ Context:
{% block labels scoped %}
{#- Labels block.
-
+
This block renders the labels for the module.
-#}
{% with labels = module.labels %}
@@ -71,7 +71,7 @@ Context:
{% filter heading(heading_level,
role="module",
id=html_id,
- toc_label=('
'|safe if config.show_symbol_type_toc else '') + module.name,
+ toc_label=('
'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name),
hidden=True,
) %}
{% endfilter %}
@@ -82,14 +82,14 @@ Context:
{% block contents scoped %}
{#- Contents block.
-
+
This block renders the contents of the module.
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 module.
-#}
{% with docstring_sections = module.docstring.parsed %}
@@ -99,7 +99,7 @@ Context:
{% block summary scoped %}
{#- Summary block.
-
+
This block renders auto-summaries for classes, methods, and attributes.
-#}
{% include "summary"|get_template with context %}
@@ -107,7 +107,7 @@ Context:
{% block children scoped %}
{#- Children block.
-
+
This block renders the children (members) of the module.
-#}
{% set root = False %}
From c9f390099f6afd08ec2f3c2923955cec7a941d64 Mon Sep 17 00:00:00 2001
From: Yann Van Crombrugge <59556820+vancromy@users.noreply.github.com>
Date: Wed, 29 Jan 2025 08:58:10 +0000
Subject: [PATCH 2/3] style: run make format
---
scripts/insiders.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/insiders.py b/scripts/insiders.py
index 849c6314..a7da99bc 100644
--- a/scripts/insiders.py
+++ b/scripts/insiders.py
@@ -26,7 +26,7 @@
def human_readable_amount(amount: int) -> str: # noqa: D103
str_amount = str(amount)
if len(str_amount) >= 4: # noqa: PLR2004
- return f"{str_amount[:len(str_amount)-3]},{str_amount[-3:]}"
+ return f"{str_amount[: len(str_amount) - 3]},{str_amount[-3:]}"
return str_amount
From 2c8528b94b6904ed048feabd68f1ac2db80b689c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?=
Date: Wed, 29 Jan 2025 17:07:01 +0100
Subject: [PATCH 3/3] Apply suggestions from code review
---
docs/usage/configuration/headings.md | 11 ++++-------
src/mkdocstrings_handlers/python/handler.py | 4 ++--
2 files changed, 6 insertions(+), 9 deletions(-)
diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md
index 099fc934..33062baf 100644
--- a/docs/usage/configuration/headings.md
+++ b/docs/usage/configuration/headings.md
@@ -62,10 +62,9 @@ plugins:
- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
-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.
+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 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.
+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
@@ -80,11 +79,9 @@ A custom string to use as the heading of the root of the object (i.e. the object
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.
+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.
+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
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
index a9b824c6..5725d566 100644
--- a/src/mkdocstrings_handlers/python/handler.py
+++ b/src/mkdocstrings_handlers/python/handler.py
@@ -145,8 +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 (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