Skip to content

Commit 0fd25e6

Browse files
pawamoypawamoy
committed
refactor: Add backlinks metadata to autorefs elements
Issue-153: #153
1 parent 40067f7 commit 0fd25e6

27 files changed

Lines changed: 115 additions & 58 deletions

‎src/mkdocstrings_handlers/python/handler.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
from __future__ import annotations
44

5+
from collections.abc import Iterable
56
import glob
67
import os
78
import posixpath
@@ -273,6 +274,11 @@ def render(self, data: CollectorItem, options: PythonOptions) -> str: # noqa: D
273274
},
274275
)
275276

277+
def render_backlinks(self, backlinks: Mapping[str, Iterable[str]]) -> str: # noqa: D102 (ignore missing docstring)
278+
template = self.env.get_template("backlinks.html.jinja")
279+
verbose_type = {key: key.capitalize().replace("-by", " by") for key in backlinks.keys()}
280+
return template.render(backlinks=backlinks, config=self.get_options({}), verbose_type=verbose_type)
281+
276282
def update_env(self, config: Any) -> None: # noqa: ARG002
277283
"""Update the Jinja environment with custom filters and tests.
278284

‎src/mkdocstrings_handlers/python/rendering.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -210,10 +210,10 @@ def do_format_attribute(
210210

211211
signature = str(attribute_path).strip()
212212
if annotations and attribute.annotation:
213-
annotation = template.render(context.parent, expression=attribute.annotation, signature=True)
213+
annotation = template.render(context.parent, expression=attribute.annotation, signature=True, backlink_type="returned-by")
214214
signature += f": {annotation}"
215215
if attribute.value:
216-
value = template.render(context.parent, expression=attribute.value, signature=True)
216+
value = template.render(context.parent, expression=attribute.value, signature=True, backlink_type="used-by")
217217
signature += f" = {value}"
218218

219219
signature = do_format_code(signature, line_length)

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,8 @@ Context:
113113
{% include "docstring"|get_template with context %}
114114
{% endwith %}
115115
{% endblock docstring %}
116+
117+
<backlinks identifier="{{ html_id }}" handler="python" />
116118
{% endblock contents %}
117119
</div>
118120

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{#- Template for backlinks.
2+
3+
This template renders backlinks.
4+
5+
Context:
6+
backlinks (Mapping[str, Iterable[str]]): The backlinks to render.
7+
config (dict): The configuration options.
8+
-#}
9+
10+
{% block logs scoped %}
11+
{#- Logging block.
12+
13+
This block can be used to log debug messages, deprecation messages, warnings, etc.
14+
-#}
15+
{{ log.debug("Rendering backlinks") }}
16+
{% endblock logs %}
17+
18+
<div class="doc doc-backlinks">
19+
{% for backlink_type, backlink_list in backlinks | dictsort %}
20+
<b class="doc doc-backlink-type">{{ verbose_type[backlink_type] }}:</b>
21+
<ul class="doc doc-backlink-list">
22+
{% for url, title in backlink_list | sort(attribute=1) %}
23+
<li><a href="{{ url }}" class="doc doc-backlink">{{ (title or url.split("#", 1)[-1]) | safe }}</a></li>
24+
{% endfor %}
25+
</ul>
26+
{% endfor %}
27+
</div>

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

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ Context:
3737
heading_level,
3838
role="class",
3939
id=html_id,
40+
title=html_id,
4041
class="doc doc-heading",
4142
toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + class.name,
4243
) %}
@@ -130,7 +131,11 @@ Context:
130131
{% if config.show_bases and class.bases %}
131132
<p class="doc doc-class-bases">
132133
Bases: {% for expression in class.bases -%}
133-
<code>{% include "expression"|get_template with context %}</code>{% if not loop.last %}, {% endif %}
134+
<code>
135+
{%- with backlink_type = "subclassed-by" -%}
136+
{%- include "expression"|get_template with context -%}
137+
{%- endwith -%}
138+
</code>{% if not loop.last %}, {% endif %}
134139
{% endfor -%}
135140
</p>
136141
{% endif %}
@@ -159,6 +164,8 @@ Context:
159164
{% endif %}
160165
{% endblock docstring %}
161166

167+
<backlinks identifier="{{ html_id }}" handler="python" />
168+
162169
{% block summary scoped %}
163170
{#- Summary block.
164171

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Context:
3636
<td><code><autoref identifier="{{ obj.path }}.{{ attribute.name }}" optional hover>{{ attribute.name }}</autoref></code></td>
3737
<td>
3838
{% if attribute.annotation %}
39-
{% with expression = attribute.annotation %}
39+
{% with expression = attribute.annotation, backlink_type = "returned-by" %}
4040
<code>{% include "expression"|get_template with context %}</code>
4141
{% endwith %}
4242
{% endif %}
@@ -60,7 +60,7 @@ Context:
6060
<li class="doc-section-item field-body">
6161
<b><code><autoref identifier="{{ obj.path }}.{{ attribute.name }}" optional hover>{{ attribute.name }}</autoref></code></b>
6262
{% if attribute.annotation %}
63-
{% with expression = attribute.annotation %}
63+
{% with expression = attribute.annotation, backlink_type = "returned-by" %}
6464
(<code>{% include "expression"|get_template with context %}</code>)
6565
{% endwith %}
6666
{% endif %}
@@ -94,7 +94,7 @@ Context:
9494
{% if attribute.annotation %}
9595
<span class="doc-attribute-annotation">
9696
<b>TYPE:</b>
97-
{% with expression = attribute.annotation %}
97+
{% with expression = attribute.annotation, backlink_type = "returned-by" %}
9898
<code>{% include "expression"|get_template with context %}</code>
9999
{% endwith %}
100100
</span>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Context:
3636
<td><code>{{ parameter.name }}</code></td>
3737
<td>
3838
{% if parameter.annotation %}
39-
{% with expression = parameter.annotation %}
39+
{% with expression = parameter.annotation, backlink_type = "used-by" %}
4040
<code>{% include "expression"|get_template with context %}</code>
4141
{% endwith %}
4242
{% endif %}
@@ -60,7 +60,7 @@ Context:
6060
<li class="doc-section-item field-body">
6161
<b><code>{{ parameter.name }}</code></b>
6262
{% if parameter.annotation %}
63-
{% with expression = parameter.annotation %}
63+
{% with expression = parameter.annotation, backlink_type = "used-by" %}
6464
(<code>{% include "expression"|get_template with context %}</code>)
6565
{% endwith %}
6666
{% endif %}
@@ -94,7 +94,7 @@ Context:
9494
{% if parameter.annotation %}
9595
<span class="doc-param-annotation">
9696
<b>{{ lang.t("TYPE:") }}</b>
97-
{% with expression = parameter.annotation %}
97+
{% with expression = parameter.annotation, backlink_type = "used-by" %}
9898
<code>{% include "expression"|get_template with context %}</code>
9999
{% endwith %}
100100
</span>

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Context:
5151
</td>
5252
<td>
5353
{% if parameter.annotation %}
54-
{% with expression = parameter.annotation %}
54+
{% with expression = parameter.annotation, backlink_type = "used-by" %}
5555
<code>{% include "expression"|get_template with context %}</code>
5656
{% endwith %}
5757
{% endif %}
@@ -63,7 +63,7 @@ Context:
6363
</td>
6464
<td>
6565
{% if parameter.default %}
66-
{% with expression = parameter.default %}
66+
{% with expression = parameter.default, backlink_type = "used-by" %}
6767
<code>{% include "expression"|get_template with context %}</code>
6868
{% endwith %}
6969
{% else %}
@@ -96,10 +96,10 @@ Context:
9696
<b><code>{{ parameter.name }}</code></b>
9797
{% endif %}
9898
{% if parameter.annotation %}
99-
{% with expression = parameter.annotation %}
99+
{% with expression = parameter.annotation, backlink_type = "used-by" %}
100100
(<code>{% include "expression"|get_template with context %}</code>
101101
{%- if parameter.default %}, {{ lang.t("default:") }}
102-
{% with expression = parameter.default %}
102+
{% with expression = parameter.default, backlink_type = "used-by" %}
103103
<code>{% include "expression"|get_template with context %}</code>
104104
{% endwith %}
105105
{% endif %})
@@ -149,15 +149,15 @@ Context:
149149
{% if parameter.annotation %}
150150
<span class="doc-param-annotation">
151151
<b>{{ lang.t("TYPE:") }}</b>
152-
{% with expression = parameter.annotation %}
152+
{% with expression = parameter.annotation, backlink_type = "used-by" %}
153153
<code>{% include "expression"|get_template with context %}</code>
154154
{% endwith %}
155155
</span>
156156
{% endif %}
157157
{% if parameter.default %}
158158
<span class="doc-param-default">
159159
<b>{{ lang.t("DEFAULT:") }}</b>
160-
{% with expression = parameter.default %}
160+
{% with expression = parameter.default, backlink_type = "used-by" %}
161161
<code>{% include "expression"|get_template with context %}</code>
162162
{% endwith %}
163163
</span>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Context:
3434
<tr class="doc-section-item">
3535
<td>
3636
{% if raises.annotation %}
37-
{% with expression = raises.annotation %}
37+
{% with expression = raises.annotation, backlink_type = "raised-by" %}
3838
<code>{% include "expression"|get_template with context %}</code>
3939
{% endwith %}
4040
{% endif %}
@@ -57,7 +57,7 @@ Context:
5757
{% for raises in section.value %}
5858
<li class="doc-section-item field-body">
5959
{% if raises.annotation %}
60-
{% with expression = raises.annotation %}
60+
{% with expression = raises.annotation, backlink_type = "raised-by" %}
6161
<code>{% include "expression"|get_template with context %}</code>
6262
{% endwith %}
6363
–
@@ -84,7 +84,7 @@ Context:
8484
<tr class="doc-section-item">
8585
<td>
8686
<span class="doc-raises-annotation">
87-
{% with expression = raises.annotation %}
87+
{% with expression = raises.annotation, backlink_type = "raised-by" %}
8888
<code>{% include "expression"|get_template with context %}</code>
8989
{% endwith %}
9090
</span>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Context:
3737
{% if name_column %}<td>{% if receives.name %}<code>{{ receives.name }}</code>{% endif %}</td>{% endif %}
3838
<td>
3939
{% if receives.annotation %}
40-
{% with expression = receives.annotation %}
40+
{% with expression = receives.annotation, backlink_type = "received-by" %}
4141
<code>{% include "expression"|get_template with context %}</code>
4242
{% endwith %}
4343
{% endif %}
@@ -61,7 +61,7 @@ Context:
6161
<li class="doc-section-item field-body">
6262
{% if receives.name %}<b><code>{{ receives.name }}</code></b>{% endif %}
6363
{% if receives.annotation %}
64-
{% with expression = receives.annotation %}
64+
{% with expression = receives.annotation, backlink_type = "received-by" %}
6565
{% if receives.name %} ({% endif %}
6666
<code>{% include "expression"|get_template with context %}</code>
6767
{% if receives.name %}){% endif %}
@@ -93,7 +93,7 @@ Context:
9393
<code>{{ receives.name }}</code>
9494
{% elif receives.annotation %}
9595
<span class="doc-receives-annotation">
96-
{% with expression = receives.annotation %}
96+
{% with expression = receives.annotation, backlink_type = "received-by" %}
9797
<code>{% include "expression"|get_template with context %}</code>
9898
{% endwith %}
9999
</span>
@@ -107,7 +107,7 @@ Context:
107107
<p>
108108
<span class="doc-receives-annotation">
109109
<b>{{ lang.t("TYPE:") }}</b>
110-
{% with expression = receives.annotation %}
110+
{% with expression = receives.annotation, backlink_type = "received-by" %}
111111
<code>{% include "expression"|get_template with context %}</code>
112112
{% endwith %}
113113
</span>

0 commit comments

Comments
 (0)