8000 fix: Use configured heading even when signature is not separated · mkdocstrings/python@096960a · GitHub
[go: up one dir, main page]
Skip to content

Commit 096960a

Browse files
pawamoypawamoy
authored
fix: Use configured heading even when signature is not separated
Issue-mkdocstrings-767: mkdocstrings/mkdocstrings#767 PR-278: #278
1 parent d4e618a commit 096960a

10 files changed

+159
-10
lines changed

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,10 @@ Context:
4848
This block renders the heading for the attribute.
4949
-#}
5050
{% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
51-
{% if config.separate_signature %}
52-
<span class="doc doc-object-name doc-attribute-name">{{ config.heading if config.heading and root else attribute_name }}</span>
51+
{% if config.heading and root %}
52+
{{ config.heading }}
53+
{% elif config.separate_signature %}
54+
<span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
5355
{% else %}
5456
{%+ filter highlight(language="python", inline=True) %}
5557
{{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %}

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,10 @@ Context:
4747
This block renders the heading for the class.
4848
-#}
4949
{% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>{% endif %}
50-
{% if config.separate_signature %}
51-
<span class="doc doc-object-name doc-class-name">{{ config.heading if config.heading and root else class_name }}</span>
50+
{% if config.heading and root %}
51+
{{ config.heading }}
52+
{% elif config.separate_signature %}
53+
<span class="doc doc-object-name doc-class-name">{{ class_name }}</span>
5254
{% elif config.merge_init_into_class and "__init__" in all_members %}
5355
{% with function = all_members["__init__"] %}
5456
{%+ filter highlight(language="python", inline=True) -%}

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,10 @@ Context:
5454
This block renders the heading for the function.
5555
-#}
5656
{% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-{{ symbol_type }}"></code>{% endif %}
57-
{% if config.separate_signature %}
58-
<span class="doc doc-object-name doc-function-name">{{ config.heading if config.heading and root else function_name }}</span>
57+
{% if config.heading and root %}
58+
{{ config.heading }}
59+
{% elif config.separate_signature %}
60+
<span class="doc doc-object-name doc-function-name">{{ function_name }}</span>
5961
{% else %}
6062
{%+ filter highlight(language="python", inline=True) -%}
6163
{#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#}

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,10 @@ Context:
4747
This block renders the heading for the module.
4848
-#}
4949
{% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-module"></code>{% endif %}
50-
{% if config.separate_signature %}
51-
<span class="doc doc-object-name doc-module-name">{{ config.heading if config.heading and root else module_name }}</span>
50+
{% if config.heading and root %}
51+
{{ config.heading }}
52+
{% elif config.separate_signature %}
53+
<span class="doc doc-object-name doc-module-name">{{ module_name }}</span>
5254
{% else %}
5355
<code>{{ module_name }}</code>
5456
{% endif %}

‎tests/snapshots/__init__.py

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -383,5 +383,23 @@
383383
(("filters", "public"), ("inherited_members", False), ("members", ("module_attribute",))): external(
384384
"80399c502938*.html",
385385
),
386+
(("heading", ""), ("members", False), ("separate_signature", False), ("show_if_no_docstring", True)): external(
387+
"d1dd339f9260*.html",
388+
),
389+
(
390+
("heading", "Some heading"),
391+
("members", False),
392+
("separate_signature", True),
393+
("show_if_no_docstring", True),
394+
): external("480324b25439*.html"),
395+
(("heading", ""), ("members", False), ("separate_signature", True), ("show_if_no_docstring", True)): external(
396+
"2eef87791b97*.html",
397+
),
398+
(
399+
("heading", "Some heading"),
400+
("members", False),
401+
("separate_signature", False),
402+
("show_if_no_docstring", True),
403+
): external("51deee0f00f3*.html"),
386404
},
387405
)

‎tests/snapshots/external/2eef87791b974c724d2cd98e40bb25994087bc836868f63da18557a6094a00ee.html

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!--
2+
{
3+
"heading": "",
4+
"members": false,
5+
"separate_signature": true,
6+
"show_if_no_docstring": true
7+
}
8+
-->
9+
10+
<div class="doc doc-object doc-module">
11+
<h1 class="doc doc-heading" id="headings_package">
12+
<span class="doc doc-object-name doc-module-name">
13+
headings_package
14+
</span>
15+
</h1>
16+
<div class="doc doc-contents first">
17+
<div class="doc doc-children">
18+
</div>
19+
</div>
20+
</div>

‎tests/snapshots/external/480324b25439ea41507fdda100045132d578af0e1df1219c08bc9ea0bea1f39c.html

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
{
3+
"heading": "Some heading",
4+
"members": false,
5+
"separate_signature": true,
6+
"show_if_no_docstring": true
7+
}
8+
-->
9+
10+
<div class="doc doc-object doc-module">
11+
<h1 class="doc doc-heading" id="headings_package">
12+
Some heading
13+
</h1>
14+
<div class="doc doc-contents first">
15+
<div class="doc doc-children">
16+
</div>
17+
</div>
18+
</div>

‎tests/snapshots/external/51deee0f00f35b0902f82fb96a36d547a80dfbb41a311dabd94b96fd968b83bc.html

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--
2+
{
3+
"heading": "Some heading",
4+
"members": false,
5+
"separate_signature": false,
6+
"show_if_no_docstring": true
7+
}
8+
-->
9+
10+
<div class="doc doc-object doc-module">
11+
<h1 class="doc doc-heading" id="headings_package">
12+
Some heading
13+
</h1>
14+
<div class="doc doc-contents first">
15+
<div class="doc doc-children">
16+
</div>
17+
</div>
18+
</div>

‎tests/snapshots/external/d1dd339f926026210ea46cc75922a8236f43cade477f95e4ce4c9a60248f0a10.html

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!--
2+
{
3+
"heading": "",
4+
"members": false,
5+
"separate_signature": false,
6+
"show_if_no_docstring": true
7+
}
8+
-->
9+
10+
<div class="doc doc-object doc-module">
11+
<h1 class="doc doc-heading" id="headings_package">
12+
<code>
13+
headings_package
14+
</code>
15+
</h1>
16+
<div class="doc doc-contents first">
17+
<div class="doc doc-children">
18+
</div>
19+
</div>
20+
</div>

‎tests/test_end_to_end.py

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ def _render_options(options: dict[str, Any]) -> str:
5959
return f"<!--\n{json.dumps(options, indent=2, sort_keys=True)}\n-->\n\n"
6060

6161

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

110110

111-
# Members options.
111+
# Member tests.
112112
@pytest.fixture(name="members_package", scope="session")
113113
def _members_package() -> Iterator[TmpPackage]:
114114
code = """
@@ -171,3 +171,50 @@ def test_end_to_end_for_members(
171171
html = _render_options(final_options) + _render(session_handler, members_package, final_options)
172172
snapshot_key = tuple(sorted(final_options.items()))
173173
assert outsource(html, suffix=".html") == snapshots_members[snapshot_key]
174+
175+
176+
# Heading tests.
177+
@pytest.fixture(name="headings_package", scope="session")
178+
def _headings_package() -> Iterator[TmpPackage]:
179+
code = """
180+
def module_function(a: int, b: str) -> None:
181+
pass
182+
183+
class Class:
184+
class_attribute: int = 42
185+
186+
def __init__(self, a: int, b: str) -> None:
187+
self.instance_attribute = a + b
188+
189+
def method1(self, a: int, b: str) -> None:
190+
pass
191+
192+
module_attribute: int = 42
193+
"""
194+
with temporary_pypackage("headings_package", {"__init__.py": code}) as tmppkg:
195+
yield tmppkg
196+
197+
198+
@pytest.mark.parametrize("separate_signature", [True, False])
199+
@pytest.mark.parametrize("heading", ["", "Some heading"])
200+
def test_end_to_end_for_headings(
201+
session_handler: PythonHandler,
202+
headings_package: TmpPackage,
203+
separate_signature: bool,
204+
heading: str,
205+
) -> None:
206+
"""Test rendering of a given theme's templates.
207+
208+
Parameters:
209+
identifier: Parametrized identifier.
210+
session_handler: Python handler (fixture).
211+
"""
212+
final_options = {
213+
"separate_signature": separate_signature,
214+
"heading": heading,
215+
"show_if_no_docstring": True,
216+
"members": False,
217+
}
218+
html = _render_options(final_options) + _render(session_handler, headings_package, final_options)
219+
snapshot_key = tuple(sorted(final_options.items()))
220+
assert outsource(html, suffix=".html") == snapshots_members[snapshot_key]

0 commit comments

Comments
 (0)
0