8000 feat: Support custom templates through objects' extra data · mkdocstrings/python@8ff2b06 · GitHub
[go: up one dir, main page]
Skip to content

Commit 8ff2b06

Browse files
pawamoypawamoy
authored
feat: Support custom templates through objects' extra data
PR #70: #70
1 parent d35f2d7 commit 8ff2b06

File tree

5 files changed

+47
-14
lines changed

5 files changed

+47
-14
lines changed

‎docs/usage/extensions.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Extensions
2+
3+
## :warning: Work in Progress!
4+
5+
The Python handler supports extensions through
6+
[*mkdocstrings*' handler extensions](https://mkdocstrings.github.io/usage/handlers/#handler-extensions).
7+
8+
Specifically, additional templates can be added to the handler,
9+
and Griffe extensions can instruct the handler to use a particular template
10+
for a particular object by setting a value in the Griffe object's `extra` dictionary:
11+
12+
```python title="griffe_extension.py"
13+
obj = ... # get a reference to a Griffe object
14+
if "mkdocstrings" not in obj.extra:
15+
obj.extra["mkdocstrings"] = {}
16+
obj.extra["mkdocstrings"]["template"] = "template_name.html"
17+
```

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ nav:
2727
- Sphinx: usage/docstrings/sphinx.md
2828
- Advanced:
2929
- Customization: usage/customization.md
30+
- Extensions: usage/extensions.md
3031
# defer to gen-files + literate-nav
3132
- Code Reference: reference/
3233
- Development:

‎src/mkdocstrings_handlers/python/handler.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -297,7 +297,8 @@ def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str: # noqa
297297
mutabled_config = dict(copy.deepcopy(config))
298298
final_config = ChainMap(mutabled_config, self.default_config)
299299

300-
template = self.env.get_template(f"{data.kind.value}.html")
300+
template_name = rendering.do_get_template(data)
301+
template = self.env.get_template(template_name)
301302

302303
# Heading level is a "state" variable, that will change at each step
303304
# of the rendering recursion. Therefore, it's easier to use it as a plain value
@@ -335,6 +336,7 @@ def update_env(self, md: Markdown, config: dict) -> None: # noqa: D102 (ignore
335336
self.env.filters["format_signature"] = rendering.do_format_signature
336337
self.env.filters["filter_objects"] = rendering.do_filter_objects
337338
self.env.filters["stash_crossref"] = lambda ref, length: ref
339+
self.env.filters["get_template"] = rendering.do_get_template
338340

339341
def get_anchors(self, data: CollectorItem) -> set[str]: # noqa: D102 (ignore missing docstring)
340342
try:

‎src/mkdocstrings_handlers/python/rendering.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,3 +248,16 @@ def formatter(code: str, line_length: int) -> str:
248248
return format_str(code, mode=mode)
249249

250250
return formatter
251+
252+
253+
def do_get_template(obj: Object) -> str:
254+
"""Get the template name used to render an object.
255+
256+
Parameters:
257+
obj: A Griffe object.
258+
259+
Returns:
260+
A template name.
261+
"""
262+
extra_data = getattr(obj, "extra", {}).get("mkdocstrings", {})
263+
return extra_data.get("template", "") or f"{obj.kind.value}.html"

‎src/mkdocstrings_handlers/python/templates/material/_base/children.html

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
{% with heading_level = heading_level + extra_level %}
2828
{% for attribute in attributes|order_members(config.members_order, members_list) %}
2929
{% if not attribute.is_alias or attribute.is_explicitely_exported %}
30-
{% include "attribute.html" with context %}
30+
{% include attribute|get_template with context %}
3131
{% endif %}
3232
{% endfor %}
3333
{% endwith %}
@@ -42,7 +42,7 @@
4242
{% with heading_level = heading_level + extra_level %}
4343
{% for class in classes|order_members(config.members_order, members_list) %}
4444
{% if not class.is_alias or class.is_explicitely_exported %}
45-
{% include "class.html" with context %}
45+
{% include class|get_template with context %}
4646
{% endif %}
4747
{% endfor %}
4848
{% endwith %}
@@ -58,7 +58,7 @@
5858
{% for function in functions|order_members(config.members_order, members_list) %}
5959
{% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
6060
{% if not function.is_alias or function.is_explicitely_exported %}
61-
{% include "function.html" with context %}
61+
{% include function|get_template with context %}
6262
{% endif %}
6363
{% endif %}
6464
{% endfor %}
@@ -75,7 +75,7 @@
7575
{% with heading_level = heading_level + extra_level %}
7676
{% for module in modules|order_members(config.members_order, members_list) %}
7777
{% if not module.is_alias or module.is_explicitely_exported %}
78-
{% include "module.html" with context %}
78+
{% include module|get_template with context %}
7979
{% endif %}
8080
{% endfor %}
8181
{% endwith %}
@@ -91,26 +91,26 @@
9191
filter_objects(filters=config.filters, members_list=members_list, keep_no_docstrings=config.show_if_no_docstring)|
9292
order_members(config.members_order, members_list) %}
9393

94-
{% if not (obj.kind.value == "class" and child.name == "__init__" and config.merge_init_into_class) %}
94+
{% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %}
9595

96-
{% if child.kind.value == "attribute" %}
96+
{% if child.is_attribute %}
9797
{% with attribute = child %}
98-
{% include "attribute.html" with context %}
98+
{% include attribute|get_template with context %}
9999
{% endwith %}
100100

101-
{% elif child.kind.value == "class" %}
101+
{% elif child.is_class %}
102102
{% with class = child %}
103-
{% include "class.html" with context %}
103+
{% include class|get_template with context %}
104104
{% endwith %}
105105

106-
{% elif child.kind.value == "function" %}
106+
{% elif child.is_function %}
107107
{% with function = child %}
108-
{% include "function.html" with context %}
108+
{% include function|get_template with context %}
109109
{% endwith %}
110110

111-
{% elif child.kind.value == "module" and config.show_submodules %}
111+
{% elif child.is_module and config.show_submodules %}
112112
{% with module = child %}
113-
{% include "module.html" with context %}
113+
{% include module|get_template with context %}
114114
{% endwith %}
115115

116116
{% endif %}

0 commit comments

Comments
 (0)
0