Skip to content

Commit a4c7bec

Browse files
pawamoypawamoy
committed
refactor: Add backlinks metadata to autorefs elements
Issue-153: #153
1 parent f883a65 commit a4c7bec

20 files changed

+60
-52
lines changed

‎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, reftype="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, reftype="used-by")
217217
signature += f" = {value}"
218218

219219
signature = do_format_code(signature, line_length)

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

Lines changed: 5 additions & 1 deletion
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 reftype = "subclassed-by" -%}
135+
{%- include "expression"|get_template with context -%}
136+
{%- endwith -%}
137+
</code>{% if not loop.last %}, {% endif %}
134138
{% endfor -%}
135139
</p>
136140
{% endif %}

‎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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "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, reftype = "received-by" %}
111111
<code>{% include "expression"|get_template with context %}</code>
112112
{% endwith %}
113113
</span>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.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 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, reftype = "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, reftype = "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, reftype = "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, reftype = "returned-by" %}
111111
<code>{% include "expression"|get_template with context %}</code>
112112
{% endwith %}
113113
</span>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.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 warns.annotation %}
37-
{% with expression = warns.annotation %}
37+
{% with expression = warns.annotation, reftype = "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, reftype = "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, reftype = "emitted-by" %}
8888
<code>{% include "expression"|get_template with context %}</code>
8989
{% endwith %}
9090
</span>

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.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 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, reftype = "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, reftype = "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, reftype = "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, reftype = "yielded-by" %}
111111
<code>{% include "expression"|get_template with context %}</code>
112112
{% endwith %}
113113
</span>

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ which is a tree-like structure representing a Python expression.
1111
-#}
1212
{% endblock logs %}
1313

14-
{%- macro crossref(name, annotation_path) -%}
14+
{%- macro crossref(name, annotation_path, reftype="") -%}
1515
{#- Output a cross-reference.
1616
1717
This macro outputs a cross-reference to the given name.
@@ -34,11 +34,11 @@ which is a tree-like structure representing a Python expression.
3434
{%- for title, path in annotation|split_path(full) -%}
3535
{%- if not signature -%}
3636
{#- Always render cross-references outside of signatures. We don't need to stash them. -#}
37-
<autoref identifier="{{ path }}" optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
37+
<autoref identifier="{{ path }}"{% if reftype %} reftype="{{ reftype }}"{% endif %} optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
3838
{%- elif config.signature_crossrefs -%}
3939
{#- We're in a signature and cross-references are enabled, we must render one and stash it. -#}
4040
{%- filter stash_crossref(length=title|length) -%}
41-
<autoref identifier="{{ path }}" optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
41+
<autoref identifier="{{ path }}" reftype="{{ reftype }}" optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
4242
{%- endfilter -%}
4343
{%- else -%}
4444
{#- We're in a signature but cross-references are disabled, we just render the title. -#}
@@ -71,7 +71,7 @@ which is a tree-like structure representing a Python expression.
7171
{%- endif -%}
7272
{%- endmacro -%}
7373

74-
{%- macro render(expression, annotations_path) -%}
74+
{%- macro render(expression, annotations_path, reftype="") -%}
7575
{#- Render an expression.
7676
7777
Parameters:
@@ -84,13 +84,13 @@ which is a tree-like structure representing a Python expression.
8484
{%- if expression is string -%}
8585
{%- if signature -%}{{ expression|safe }}{%- else -%}{{ expression }}{%- endif -%}
8686
{%- elif expression.classname == "ExprName" -%}
87-
{{ crossref(expression, annotations_path) }}
87+
{{ crossref(expression, annotations_path, reftype) }}
8888
{%- elif config.unwrap_annotated and expression.classname == "ExprSubscript" and expression.canonical_path in ("typing.Annotated", "typing_extensions.Annotated") -%}
8989
{{ render(expression.slice.elements[0], annotations_path) }}
9090
{%- elif expression.classname == "ExprAttribute" -%}
9191
{%- if annotations_path == "brief" -%}
9292
{%- if expression.last.is_enum_value -%}
93-
{{ crossref(expression.last.parent, "brief") }}.value
93+
{{ crossref(expression.last.parent, "brief", reftype) }}.value
9494
{%- else -%}
9595
{{ render(expression.last, "brief") }}
9696
{%- endif -%}
@@ -115,4 +115,4 @@ which is a tree-like structure representing a Python expression.
115115
{%- endif -%}
116116
{%- endmacro -%}
117117

118-
{{ render(expression, config.annotations_path) }}
118+
{{ render(expression, config.annotations_path, reftype|default("")) }}

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

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,9 @@ Context:
4949
{%- set ns.equal = " = " -%}
5050
{%- if config.separate_signature and config.signature_crossrefs -%}
5151
{%- with expression = parameter.annotation -%}
52-
{%- set ns.annotation -%}: {% include "expression"|get_template with context %}{%- endset -%}
52+
{%- set ns.annotation -%}: {% with reftype = "used-by" -%}
53+
{%- include "expression"|get_template with context -%}
54+
{%- endwith -%}{%- endset -%}
5355
{%- endwith -%}
5456
{%- else -%}
5557
{%- set ns.annotation = ": " + parameter.annotation|safe -%}
@@ -102,7 +104,7 @@ Context:
102104
{%- if ns.default -%}
103105
{{ ns.equal }}
104106
{%- if config.signature_crossrefs and config.separate_signature -%}
105-
{%- with expression = parameter.default -%}
107+
{%- with expression = parameter.default, reftype = "used-by" -%}
106108
{%- include "expression"|get_template with context -%}
107109
{%- endwith -%}
108110
{%- else -%}
@@ -121,7 +123,9 @@ Context:
121123
and function.annotation
122124
and not (config.merge_init_into_class and function.name == "__init__" )
123125
%} -> {% if config.separate_signature and config.signature_crossrefs -%}
124-
{%- with expression = function.annotation %}{% include "expression"|get_template with context %}{%- endwith -%}
126+
{%- with expression = function.annotation, reftype = "returned-by" -%}
127+
{%- include "expression"|get_template with context -%}
128+
{%- endwith -%}
125129
{%- else -%}
126130
{{ function.annotation|safe }}
127131
{%- endif -%}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Context:
3232
<li>
3333
<b><code>{{ attribute.name }}</code></b>
3434
{% if attribute.annotation %}
35-
{% with expression = attribute.annotation %}
35+
{% with expression = attribute.annotation, reftype = "returned-by" %}
3636
(<code>{% include "expression"|get_template with context %}</code>)
3737
{% endwith %}
3838
{% endif %}

0 commit comments

Comments
 (0)