mkdocstrings · pawamoy · May 20, 2025 · May 20, 2025
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
@@ -48,8 +48,10 @@ Context:
          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">{{ config.heading if config.heading and root else attribute_name }}</span>
+          {% if config.heading and root %}
+            {{ config.heading }}
+          {% elif config.separate_signature %}
+            <span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
          {% else %}
            {%+ filter highlight(language="python", inline=True) %}
              {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja
@@ -47,8 +47,10 @@ Context:
          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">{{ config.heading if config.heading and root else class_name }}</span>
+          {% if config.heading and root %}
+            {{ config.heading }}
+          {% elif config.separate_signature %}
+            <span class="doc doc-object-name doc-class-name">{{ 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) -%}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja
@@ -54,8 +54,10 @@ Context:
          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">{{ config.heading if config.heading and root else function_name }}</span>
+          {% if config.heading and root %}
+            {{ config.heading }}
+          {% elif config.separate_signature %}
+            <span class="doc doc-object-name doc-function-name">{{ function_name }}</span>
          {% else %}
            {%+ filter highlight(language="python", inline=True) -%}
              {#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#}

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja
@@ -47,8 +47,10 @@ Context:
          This block renders the heading for the module.
          -#}
          {% 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">{{ config.heading if config.heading and root else module_name }}</span>
+          {% if config.heading and root %}
+            {{ config.heading }}
+          {% elif config.separate_signature %}
+            <span class="doc doc-object-name doc-module-name">{{ module_name }}</span>
          {% else %}
            <code>{{ module_name }}</code>
          {% endif %}

diff --git a/tests/snapshots/__init__.py b/tests/snapshots/__init__.py
@@ -383,5 +383,23 @@
        (("filters", "public"), ("inherited_members", False), ("members", ("module_attribute",))): external(
            "80399c502938*.html",
        ),
+        (("heading", ""), ("members", False), ("separate_signature", False), ("show_if_no_docstring", True)): external(
+            "d1dd339f9260*.html",
+        ),
+        (
+            ("heading", "Some heading"),
+            ("members", False),
+            ("separate_signature", True),
+            ("show_if_no_docstring", True),
+        ): external("480324b25439*.html"),
+        (("heading", ""), ("members", False), ("separate_signature", True), ("show_if_no_docstring", True)): external(
+            "2eef87791b97*.html",
+        ),
+        (
+            ("heading", "Some heading"),
+            ("members", False),
+            ("separate_signature", False),
+            ("show_if_no_docstring", True),
+        ): external("51deee0f00f3*.html"),
    },
 )
diff --git a/.../snapshots/external/2eef87791b974c724d2cd98e40bb25994087bc836868f63da18557a6094a00ee.html b/.../snapshots/external/2eef87791b974c724d2cd98e40bb25994087bc836868f63da18557a6094a00ee.html
@@ -0,0 +1,20 @@
+<!--
+{
+  "heading": "",
+  "members": false,
+  "separate_signature": true,
+  "show_if_no_docstring": true
+}
+-->
+
+<div class="doc doc-object doc-module">
+ <h1 class="doc doc-heading" id="headings_package">
+  <span class="doc doc-object-name doc-module-name">
+   headings_package
+  </span>
+ </h1>
+ <div class="doc doc-contents first">
+  <div class="doc doc-children">
+  </div>
+ </div>
+</div>
diff --git a/.../snapshots/external/480324b25439ea41507fdda100045132d578af0e1df1219c08bc9ea0bea1f39c.html b/.../snapshots/external/480324b25439ea41507fdda100045132d578af0e1df1219c08bc9ea0bea1f39c.html
@@ -0,0 +1,18 @@
+<!--
+{
+  "heading": "Some heading",
+  "members": false,
+  "separate_signature": true,
+  "show_if_no_docstring": true
+}
+-->
+
+<div class="doc doc-object doc-module">
+ <h1 class="doc doc-heading" id="headings_package">
+  Some heading
+ </h1>
+ <div class="doc doc-contents first">
+  <div class="doc doc-children">
+  </div>
+ </div>
+</div>
diff --git a/.../snapshots/external/51deee0f00f35b0902f82fb96a36d547a80dfbb41a311dabd94b96fd968b83bc.html b/.../snapshots/external/51deee0f00f35b0902f82fb96a36d547a80dfbb41a311dabd94b96fd968b83bc.html
@@ -0,0 +1,18 @@
+<!--
+{
+  "heading": "Some heading",
+  "members": false,
+  "separate_signature": false,
+  "show_if_no_docstring": true
+}
+-->
+
+<div class="doc doc-object doc-module">
+ <h1 class="doc doc-heading" id="headings_package">
+  Some heading
+ </h1>
+ <div class="doc doc-contents first">
+  <div class="doc doc-children">
+  </div>
+ </div>
+</div>
diff --git a/.../snapshots/external/d1dd339f926026210ea46cc75922a8236f43cade477f95e4ce4c9a60248f0a10.html b/.../snapshots/external/d1dd339f926026210ea46cc75922a8236f43cade477f95e4ce4c9a60248f0a10.html
@@ -0,0 +1,20 @@
+<!--
+{
+  "heading": "",
+  "members": false,
+  "separate_signature": false,
+  "show_if_no_docstring": true
+}
+-->
+
+<div class="doc doc-object doc-module">
+ <h1 class="doc doc-heading" id="headings_package">
+  <code>
+   headings_package
+  </code>
+ </h1>
+ <div class="doc doc-contents first">
+  <div class="doc doc-children">
+  </div>
+ </div>
+</div>
diff --git a/tests/test_end_to_end.py b/tests/test_end_to_end.py
@@ -59,7 +59,7 @@ def _render_options(options: dict[str, Any]) -> str:
    return f"<!--\n{json.dumps(options, indent=2, sort_keys=True)}\n-->\n\n"


-# Signature options
+# Signature tests.
 @pytest.fixture(name="signature_package", scope="session")
 def _signature_package() -> Iterator[TmpPackage]:
    code = """
@@ -108,7 +108,7 @@ def test_end_to_end_for_signatures(
    assert outsource(html, suffix=".html") == snapshots_signatures[snapshot_key]


-# Members options.
+# Member tests.
 @pytest.fixture(name="members_package", scope="session")
 def _members_package() -> Iterator[TmpPackage]:
    code = """
@@ -171,3 +171,50 @@ def test_end_to_end_for_members(
    html = _render_options(final_options) + _render(session_handler, members_package, final_options)
    snapshot_key = tuple(sorted(final_options.items()))
    assert outsource(html, suffix=".html") == snapshots_members[snapshot_key]
+
+
+# Heading tests.
+@pytest.fixture(name="headings_package", scope="session")
+def _headings_package() -> Iterator[TmpPackage]:
+    code = """
+        def module_function(a: int, b: str) -> None:
+            pass
+
+        class Class:
+            class_attribute: int = 42
+
+            def __init__(self, a: int, b: str) -> None:
+                self.instance_attribute = a + b
+
+            def method1(self, a: int, b: str) -> None:
+                pass
+
+        module_attribute: int = 42
+    """
+    with temporary_pypackage("headings_package", {"__init__.py": code}) as tmppkg:
+        yield tmppkg
+
+
+@pytest.mark.parametrize("separate_signature", [True, False])
+@pytest.mark.parametrize("heading", ["", "Some heading"])
+def test_end_to_end_for_headings(
+    session_handler: PythonHandler,
+    headings_package: TmpPackage,
+    separate_signature: bool,
+    heading: str,
+) -> None:
+    """Test rendering of a given theme's templates.
+
+    Parameters:
+        identifier: Parametrized identifier.
+        session_handler: Python handler (fixture).
+    """
+    final_options = {
+        "separate_signature": separate_signature,
+        "heading": heading,
+        "show_if_no_docstring": True,
+        "members": False,
+    }
+    html = _render_options(final_options) + _render(session_handler, headings_package, final_options)
+    snapshot_key = tuple(sorted(final_options.items()))
+    assert outsource(html, suffix=".html") == snapshots_members[snapshot_key]