Skip to content

Commit e810784

Browse files
pawamoypawamoy
committed
feat: Support backlinks
Issue-153: #153
1 parent 15a7009 commit e810784

25 files changed

+139
-54
lines changed

Diff for: ‎src/mkdocstrings_handlers/python/handler.py

+7
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
@@ -33,6 +34,7 @@
3334
from collections.abc import Iterator, Mapping, MutableMapping, Sequence
3435

3536
from mkdocs.config.defaults import MkDocsConfig
37+
from mkdocs_autorefs.plugin import Backlink
3638

3739

3840
if sys.version_info >= (3, 11):
@@ -280,6 +282,11 @@ def render(self, data: CollectorItem, options: PythonOptions) -> str: # noqa: D
280282
},
281283
)
282284

285+
def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]]) -> str: # noqa: D102 (ignore missing docstring)
286+
template = self.env.get_template("backlinks.html.jinja")
287+
verbose_type = {key: key.capitalize().replace("-by", " by") for key in backlinks.keys()}
288+
return template.render(backlinks=backlinks, config=self.get_options({}), verbose_type=verbose_type)
289+
283290
def update_env(self, config: Any) -> None: # noqa: ARG002
284291
"""Update the Jinja environment with custom filters and tests.
285292

Diff for: ‎src/mkdocstrings_handlers/python/rendering.py

+2-2
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)

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

+2
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

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

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
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 backlink in backlink_list | sort(attribute="crumbs") %}
23+
<li class="doc doc-backlink">
24+
{% for crumb in backlink.crumbs %}
25+
<span class="doc doc-backlink-crumb">
26+
{% if crumb.url and crumb.title %}
27+
<a href="{{ crumb.url }}">{{ crumb.title | safe }}</a>
28+
{% elif crumb.title %}
29+
<span>{{ crumb.title | safe }}</span>
30+
{% endif %}
31+
</span>
32+
{% endfor %}
33+
</li>
34+
{% endfor %}
35+
</ul>
36+
{% endfor %}
37+
</div>

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

+7-1
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,11 @@ Context:
130130
{% if config.show_bases and class.bases %}
131131
<p class="doc doc-class-bases">
132132
Bases: {% for expression in class.bases -%}
133-
<code>{% include "expression"|get_template with context %}</code>{% if not loop.last %}, {% endif %}
133+
<code>
134+
{%- with backlink_type = "subclassed-by" -%}
135+
{%- include "expression"|get_template with context -%}
136+
{%- endwith -%}
137+
</code>{% if not loop.last %}, {% endif %}
134138
{% endfor -%}
135139
</p>
136140
{% endif %}
@@ -159,6 +163,8 @@ Context:
159163
{% endif %}
160164
{% endblock docstring %}
161165

166+
<backlinks identifier="{{ html_id }}" handler="python" />
167+
162168
{% block summary scoped %}
163169
{#- Summary block.
164170

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

+3-3
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>

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

+6-6
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>

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

+3-3
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>

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

+4-4
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>

Diff for: ‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja

+4-4
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Context:
3737
{% if name_column %}<td>{% if returns.name %}<code>{{ returns.name }}</code>{% endif %}</td>{% endif %}
3838
<td>
3939
{% if returns.annotation %}
40-
{% with expression = returns.annotation %}
40+
{% with expression = returns.annotation, backlink_type = "returned-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 returns.name %}<b><code>{{ returns.name }}</code></b>{% endif %}
6363
{% if returns.annotation %}
64-
{% with expression = returns.annotation %}
64+
{% with expression = returns.annotation, backlink_type = "returned-by" %}
6565
{% if returns.name %} ({% endif %}
6666
<code>{% include "expression"|get_template with context %}</code>
6767
{% if returns.name %}){% endif %}
@@ -93,7 +93,7 @@ Context:
9393
<code>{{ returns.name }}</code>
9494
{% elif returns.annotation %}
9595
<span class="doc-returns-annotation">
96-
{% with expression = returns.annotation %}
96+
{% with expression = returns.annotation, backlink_type = "returned-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-returns-annotation">
109109
<b>{{ lang.t("TYPE:") }}</b>
110-
{% with expression = returns.annotation %}
110+
{% with expression = returns.annotation, backlink_type = "returned-by" %}
111111
<code>{% include "expression"|get_template with context %}</code>
112112
{% endwith %}
113113
</span>

Diff for: ‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja

+3-3
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Context:
3434
<tr class="doc-section-item">
3535
<td>
3636
{% if warns.annotation %}
37-
{% with expression = warns.annotation %}
37+
{% with expression = warns.annotation, backlink_type = "emitted-by" %}
3838
<code>{% include "expression"|get_template with context %}</code>
3939
{% endwith %}
4040
{% endif %}
@@ -57,7 +57,7 @@ Context:
5757
{% for warns in section.value %}
5858
<li class="doc-section-item field-body">
5959
{% if warns.annotation %}
60-
{% with expression = warns.annotation %}
60+
{% with expression = warns.annotation, backlink_type = "emitted-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-warns-annotation">
87-
{% with expression = warns.annotation %}
87+
{% with expression = warns.annotation, backlink_type = "emitted-by" %}
8888
<code>{% include "expression"|get_template with context %}</code>
8989
{% endwith %}
9090
</span>

Diff for: ‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja

+4-4
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Context:
3737
{% if name_column %}<td>{% if yields.name %}<code>{{ yields.name }}</code>{% endif %}</td>{% endif %}
3838
<td>
3939
{% if yields.annotation %}
40-
{% with expression = yields.annotation %}
40+
{% with expression = yields.annotation, backlink_type = "yielded-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 yields.name %}<b><code>{{ yields.name }}</code></b>{% endif %}
6363
{% if yields.annotation %}
64-
{% with expression = yields.annotation %}
64+
{% with expression = yields.annotation, backlink_type = "yielded-by" %}
6565
{% if yields.name %} ({% endif %}
6666
<code>{% include "expression"|get_template with context %}</code>
6767
{% if yields.name %}){% endif %}
@@ -93,7 +93,7 @@ Context:
9393
<code>{{ yields.name }}</code>
9494
{% elif yields.annotation %}
9595
<span class="doc-yields-annotation">
96-
{% with expression = yields.annotation %}
96+
{% with expression = yields.annotation, backlink_type = "yielded-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-yields-annotation">
109109
<b>{{ lang.t("TYPE:") }}:</b>
110-
{% with expression = yields.annotation %}
110+
{% with expression = yields.annotation, backlink_type = "yielded-by" %}
111111
<code>{% include "expression"|get_template with context %}</code>
112112
{% endwith %}
113113
</span>

0 commit comments

Comments
 (0)