mkdocstrings-python 1.16.4__tar.gz → 1.16.5__tar.gz

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/CHANGELOG.md

@@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [1.16.5](https://github.com/mkdocstrings/python/releases/tag/1.16.5) - 2025-03-10
+
+<small>[Compare with 1.16.4](https://github.com/mkdocstrings/python/compare/1.16.4...1.16.5)</small>
+
+### Code Refactoring
+
+- Prepare backlinks support ([56bf627](https://github.com/mkdocstrings/python/commit/56bf627b9483a12228b769ae4690b84733061ea5) by Timothée Mazzucotelli). [Issue-153](https://github.com/mkdocstrings/python/issues/153), [PR-252](https://github.com/mkdocstrings/python/pull/252)
+
 ## [1.16.4](https://github.com/mkdocstrings/python/releases/tag/1.16.4) - 2025-03-10
 
 <small>[Compare with 1.16.3](https://github.com/mkdocstrings/python/compare/1.16.3...1.16.4)</small>

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mkdocstrings-python
-Version: 1.16.4
+Version: 1.16.5
 Summary: A Python handler for mkdocstrings.
 Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
 License: ISC

mkdocstrings_python-1.16.5/docs/css/mkdocstrings.css

@@ -0,0 +1,72 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: currentColor;
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}
+
+/* Tree-like output for backlinks. */
+.doc-backlink-list {
+  --tree-clr: var(--md-default-fg-color);
+  --tree-font-size: 1rem;
+  --tree-item-height: 1;
+  --tree-offset: 1rem;
+  --tree-thickness: 1px;
+  --tree-style: solid;
+  display: grid;
+  list-style: none !important;
+}
+
+.doc-backlink-list li > span:first-child {
+  text-indent: .3rem;
+}
+.doc-backlink-list li {
+  padding-inline-start: var(--tree-offset);
+  border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr);
+  position: relative;
+  margin-left: 0 !important;
+
+  &:last-child {
+    border-color: transparent;
+  }
+  &::before{
+    content: '';
+    position: absolute;
+    top: calc(var(--tree-item-height) / 2 * -1 * var(--tree-font-size) + var(--tree-thickness));
+    left: calc(var(--tree-thickness) * -1);
+    width: calc(var(--tree-offset) + var(--tree-thickness) * 2);
+    height: calc(var(--tree-item-height)  * var(--tree-font-size));
+    border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr);
+    border-bottom: var(--tree-thickness) var(--tree-style) var(--tree-clr);
+  }
+  &::after{
+    content: '';
+    position: absolute;
+    border-radius: 50%;
+    background-color: var(--tree-clr);
+    top: calc(var(--tree-item-height) / 2 * 1rem);
+    left: var(--tree-offset) ;
+    translate: calc(var(--tree-thickness) * -1) calc(var(--tree-thickness) * -1);
+  }
+}

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/docs/insiders/changelog.md

@@ -2,6 +2,10 @@
 
 ## mkdocstrings-python Insiders
 
+### 1.10.0 <small>March 10, 2025</small> { id="1.10.0" }
+
+- [Backlinks][backlinks]
+
 ### 1.9.0 <small>September 03, 2024</small> { id="1.9.0" }
 
 - [Relative cross-references][relative_crossrefs]

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/docs/insiders/goals.yml

@@ -42,3 +42,6 @@ goals:
     - name: Scoped cross-references
       ref: /usage/configuration/docstrings/#scoped_crossrefs
       since: 2024/09/03
+    - name: Backlinks
+      ref: /usage/configuration/general/#backlinks
+      since: 2025/03/10

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/docs/usage/configuration/general.md

@@ -60,6 +60,38 @@ plugins:
 ////
 ///
 
+[](){#option-backlinks}
+## `backlinks`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
+[:octicons-tag-24: Insiders 1.10.0](../../insiders/changelog.md#1.10.0)
+
+- **:octicons-package-24: Type <code><autoref identifier="typing.Literal" optional>Literal</autoref>["flat", "tree", False]</code> :material-equal: `False`{ title="default value" }**
+
+The `backlinks` option enables rendering of backlinks within your API documentation.
+
+When an arbitrary section of your documentation links to an API symbol, this link will be collected as a backlink, and rendered below your API symbol. In short, the API symbol will link back to the section that links to it. Such backlinks will help your users navigate the documentation, as they will immediately which functions return a specific symbol, or where a specific symbol is accepted as parameter, etc..
+
+Each backlink is a list of breadcrumbs that represent the navigation, from the root page down to the given section.
+
+The available styles for rendering backlinks are **`flat`** and **`tree`**.
+
+- **`flat`** will render backlinks as a single-layer list. This can lead to repetition of breadcrumbs.
+- **`tree`** will combine backlinks into a tree, to remove repetition of breadcrumbs.
+
+WARNING: **Global-only option.** For now, the option only works when set globally in `mkdocs.yml`.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          backlinks: tree
+```
+
+<!-- TODO: Add screenshots! -->
+
 [](){#option-extensions}
 ## `extensions`
 

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/mkdocs.yml

@@ -160,6 +160,7 @@ plugins:
         - https://mkdocstrings.github.io/griffe/objects.inv
         - https://python-markdown.github.io/objects.inv
         options:
+          backlinks: tree
           docstring_options:
             ignore_init_summary: true
           docstring_section_style: list

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/pyproject.toml

@@ -38,7 +38,7 @@ dependencies = [
     "griffe>=0.49",
     "typing-extensions>=4.0; python_version < '3.11'",
 ]
-version = "1.16.4"
+version = "1.16.5"
 
 [project.license]
 text = "ISC"

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/config.py

@@ -386,6 +386,14 @@ class PythonInputOptions:
         ),
     ] = "brief"
 
+    backlinks: Annotated[
+        Literal["flat", "tree", False],
+        Field(
+            group="general",
+            description="Whether to render backlinks, and how.",
+        ),
+    ] = False
+
     docstring_options: Annotated[
         GoogleStyleOptions | NumpyStyleOptions | SphinxStyleOptions | AutoStyleOptions | None,
         Field(

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/handler.py

@@ -301,6 +301,7 @@ class PythonHandler(BaseHandler):
         self.env.filters["as_functions_section"] = rendering.do_as_functions_section
         self.env.filters["as_classes_section"] = rendering.do_as_classes_section
         self.env.filters["as_modules_section"] = rendering.do_as_modules_section
+        self.env.filters["backlink_tree"] = rendering.do_backlink_tree
         self.env.globals["AutorefsHook"] = rendering.AutorefsHook
         self.env.tests["existing_template"] = lambda template_name: template_name in self.env.list_templates()
 

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/rendering.py

@@ -8,11 +8,12 @@ import string
 import subprocess
 import sys
 import warnings
+from collections import defaultdict
 from dataclasses import replace
 from functools import lru_cache
 from pathlib import Path
 from re import Match, Pattern
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal, TypeVar
 
 from griffe import (
     Alias,
@@ -28,11 +29,11 @@ from griffe import (
 )
 from jinja2 import TemplateNotFound, pass_context, pass_environment
 from markupsafe import Markup
-from mkdocs_autorefs import AutorefsHookInterface
+from mkdocs_autorefs import AutorefsHookInterface, Backlink, BacklinkCrumb
 from mkdocstrings import get_logger
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence
+    from collections.abc import Iterable, Iterator, Sequence
 
     from griffe import Attribute, Class, Function, Module
     from jinja2 import Environment, Template
@@ -210,10 +211,15 @@ def do_format_attribute(
 
     signature = str(attribute_path).strip()
     if annotations and attribute.annotation:
-        annotation = template.render(context.parent, expression=attribute.annotation, signature=True)
+        annotation = template.render(
+            context.parent,
+            expression=attribute.annotation,
+            signature=True,
+            backlink_type="returned-by",
+        )
         signature += f": {annotation}"
     if attribute.value:
-        value = template.render(context.parent, expression=attribute.value, signature=True)
+        value = template.render(context.parent, expression=attribute.value, signature=True, backlink_type="used-by")
         signature += f" = {value}"
 
     signature = do_format_code(signature, line_length)
@@ -725,3 +731,45 @@ class AutorefsHook(AutorefsHookInterface):
             filepath=str(filepath),
             lineno=lineno,
         )
+
+
+T = TypeVar("T")
+Tree = dict[T, "Tree"]
+CompactTree = dict[tuple[T, ...], "CompactTree"]
+_rtree = lambda: defaultdict(_rtree)  # type: ignore[has-type,var-annotated]  # noqa: E731
+
+
+def _tree(data: Iterable[tuple[T, ...]]) -> Tree:
+    new_tree = _rtree()
+    for nav in data:
+        *path, leaf = nav
+        node = new_tree
+        for key in path:
+            node = node[key]
+        node[leaf] = _rtree()
+    return new_tree
+
+
+def _compact_tree(tree: Tree) -> CompactTree:
+    new_tree = _rtree()
+    for key, value in tree.items():
+        child = _compact_tree(value)
+        if len(child) == 1:
+            child_key, child_value = next(iter(child.items()))
+            new_key = (key, *child_key)
+            new_tree[new_key] = child_value
+        else:
+            new_tree[(key,)] = child
+    return new_tree
+
+
+def do_backlink_tree(backlinks: list[Backlink]) -> CompactTree[BacklinkCrumb]:
+    """Build a tree of backlinks.
+
+    Parameters:
+        backlinks: The list of backlinks.
+
+    Returns:
+        A tree of backlinks.
+    """
+    return _compact_tree(_tree(backlink.crumbs for backlink in backlinks))

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja

@@ -113,6 +113,10 @@ Context:
             {% include "docstring"|get_template with context %}
           {% endwith %}
         {% endblock docstring %}
+
+        {% if config.backlinks %}
+          <backlinks identifier="{{ html_id }}" handler="python" />
+        {% endif %}
       {% endblock contents %}
     </div>
 

mkdocstrings_python-1.16.5/src/mkdocstrings_handlers/python/templates/material/_base/backlinks.html.jinja

@@ -0,0 +1,17 @@
+{#- Template for backlinks.
+
+This template renders backlinks.
+
+Context:
+  backlinks (Mapping[str, Iterable[str]]): The backlinks to render.
+  config (dict): The configuration options.
+  verbose_type (Mapping[str, str]): The verbose backlink types.
+  default_crumb (BacklinkCrumb): A default, empty crumb.
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+{% endblock logs %}

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja

@@ -130,7 +130,11 @@ Context:
           {% if config.show_bases and class.bases %}
             <p class="doc doc-class-bases">
               Bases: {% for expression in class.bases -%}
-                <code>{% include "expression"|get_template with context %}</code>{% if not loop.last %}, {% endif %}
+                <code>
+                  {%- with backlink_type = "subclassed-by" -%}
+                    {%- include "expression"|get_template with context -%}
+                  {%- endwith -%}
+                </code>{% if not loop.last %}, {% endif %}
               {% endfor -%}
             </p>
           {% endif %}
@@ -159,6 +163,10 @@ Context:
           {% endif %}
         {% endblock docstring %}
 
+        {% if config.backlinks %}
+          <backlinks identifier="{{ html_id }}" handler="python" />
+        {% endif %}
+
         {% block summary scoped %}
           {#- Summary block.
 

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja

@@ -36,7 +36,7 @@ Context:
             <td><code>{{ parameter.name }}</code></td>
             <td>
               {% if parameter.annotation %}
-                {% with expression = parameter.annotation %}
+                {% with expression = parameter.annotation, backlink_type = "used-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %}
@@ -60,7 +60,7 @@ Context:
         <li class="doc-section-item field-body">
           <b><code>{{ parameter.name }}</code></b>
           {% if parameter.annotation %}
-            {% with expression = parameter.annotation %}
+            {% with expression = parameter.annotation, backlink_type = "used-by" %}
               (<code>{% include "expression"|get_template with context %}</code>)
             {% endwith %}
           {% endif %}
@@ -94,7 +94,7 @@ Context:
                 {% if parameter.annotation %}
                   <span class="doc-param-annotation">
                     <b>{{ lang.t("TYPE:") }}</b>
-                    {% with expression = parameter.annotation %}
+                    {% with expression = parameter.annotation, backlink_type = "used-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja

@@ -51,7 +51,7 @@ Context:
             </td>
             <td>
               {% if parameter.annotation %}
-                {% with expression = parameter.annotation %}
+                {% with expression = parameter.annotation, backlink_type = "used-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %}
@@ -63,7 +63,7 @@ Context:
             </td>
             <td>
               {% if parameter.default %}
-                {% with expression = parameter.default %}
+                {% with expression = parameter.default, backlink_type = "used-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% else %}
@@ -96,10 +96,10 @@ Context:
             <b><code>{{ parameter.name }}</code></b>
           {% endif %}
           {% if parameter.annotation %}
-            {% with expression = parameter.annotation %}
+            {% with expression = parameter.annotation, backlink_type = "used-by" %}
               (<code>{% include "expression"|get_template with context %}</code>
               {%- if parameter.default %}, {{ lang.t("default:") }}
-                {% with expression = parameter.default %}
+                {% with expression = parameter.default, backlink_type = "used-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %})
@@ -149,7 +149,7 @@ Context:
                 {% if parameter.annotation %}
                   <span class="doc-param-annotation">
                     <b>{{ lang.t("TYPE:") }}</b>
-                    {% with expression = parameter.annotation %}
+                    {% with expression = parameter.annotation, backlink_type = "used-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>
@@ -157,7 +157,7 @@ Context:
                 {% if parameter.default %}
                   <span class="doc-param-default">
                     <b>{{ lang.t("DEFAULT:") }}</b>
-                    {% with expression = parameter.default %}
+                    {% with expression = parameter.default, backlink_type = "used-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja

@@ -34,7 +34,7 @@ Context:
           <tr class="doc-section-item">
             <td>
               {% if raises.annotation %}
-                {% with expression = raises.annotation %}
+                {% with expression = raises.annotation, backlink_type = "raised-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %}
@@ -57,7 +57,7 @@ Context:
       {% for raises in section.value %}
         <li class="doc-section-item field-body">
           {% if raises.annotation %}
-            {% with expression = raises.annotation %}
+            {% with expression = raises.annotation, backlink_type = "raised-by" %}
               <code>{% include "expression"|get_template with context %}</code>
             {% endwith %}
             –
@@ -84,7 +84,7 @@ Context:
           <tr class="doc-section-item">
             <td>
               <span class="doc-raises-annotation">
-                {% with expression = raises.annotation %}
+                {% with expression = raises.annotation, backlink_type = "raised-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               </span>

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja

@@ -37,7 +37,7 @@ Context:
             {% if name_column %}<td>{% if receives.name %}<code>{{ receives.name }}</code>{% endif %}</td>{% endif %}
             <td>
               {% if receives.annotation %}
-                {% with expression = receives.annotation %}
+                {% with expression = receives.annotation, backlink_type = "received-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %}
@@ -61,7 +61,7 @@ Context:
         <li class="doc-section-item field-body">
           {% if receives.name %}<b><code>{{ receives.name }}</code></b>{% endif %}
           {% if receives.annotation %}
-            {% with expression = receives.annotation %}
+            {% with expression = receives.annotation, backlink_type = "received-by" %}
               {% if receives.name %} ({% endif %}
               <code>{% include "expression"|get_template with context %}</code>
               {% if receives.name %}){% endif %}
@@ -93,7 +93,7 @@ Context:
                 <code>{{ receives.name }}</code>
               {% elif receives.annotation %}
                 <span class="doc-receives-annotation">
-                  {% with expression = receives.annotation %}
+                  {% with expression = receives.annotation, backlink_type = "received-by" %}
                     <code>{% include "expression"|get_template with context %}</code>
                   {% endwith %}
                 </span>
@@ -107,7 +107,7 @@ Context:
                 <p>
                   <span class="doc-receives-annotation">
                     <b>{{ lang.t("TYPE:") }}</b>
-                    {% with expression = receives.annotation %}
+                    {% with expression = receives.annotation, backlink_type = "received-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja

@@ -37,7 +37,7 @@ Context:
             {% if name_column %}<td>{% if returns.name %}<code>{{ returns.name }}</code>{% endif %}</td>{% endif %}
             <td>
               {% if returns.annotation %}
-                {% with expression = returns.annotation %}
+                {% with expression = returns.annotation, backlink_type = "returned-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %}
@@ -61,7 +61,7 @@ Context:
         <li class="doc-section-item field-body">
           {% if returns.name %}<b><code>{{ returns.name }}</code></b>{% endif %}
           {% if returns.annotation %}
-            {% with expression = returns.annotation %}
+            {% with expression = returns.annotation, backlink_type = "returned-by" %}
               {% if returns.name %} ({% endif %}
               <code>{% include "expression"|get_template with context %}</code>
               {% if returns.name %}){% endif %}
@@ -93,7 +93,7 @@ Context:
                 <code>{{ returns.name }}</code>
               {% elif returns.annotation %}
                 <span class="doc-returns-annotation">
-                  {% with expression = returns.annotation %}
+                  {% with expression = returns.annotation, backlink_type = "returned-by" %}
                     <code>{% include "expression"|get_template with context %}</code>
                   {% endwith %}
                 </span>
@@ -107,7 +107,7 @@ Context:
                 <p>
                   <span class="doc-returns-annotation">
                     <b>{{ lang.t("TYPE:") }}</b>
-                    {% with expression = returns.annotation %}
+                    {% with expression = returns.annotation, backlink_type = "returned-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja

@@ -34,7 +34,7 @@ Context:
           <tr class="doc-section-item">
             <td>
               {% if warns.annotation %}
-                {% with expression = warns.annotation %}
+                {% with expression = warns.annotation, backlink_type = "emitted-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %}
@@ -57,7 +57,7 @@ Context:
       {% for warns in section.value %}
         <li class="doc-section-item field-body">
           {% if warns.annotation %}
-            {% with expression = warns.annotation %}
+            {% with expression = warns.annotation, backlink_type = "emitted-by" %}
               <code>{% include "expression"|get_template with context %}</code>
             {% endwith %}
             –
@@ -84,7 +84,7 @@ Context:
           <tr class="doc-section-item">
             <td>
               <span class="doc-warns-annotation">
-                {% with expression = warns.annotation %}
+                {% with expression = warns.annotation, backlink_type = "emitted-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               </span>

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja

@@ -37,7 +37,7 @@ Context:
             {% if name_column %}<td>{% if yields.name %}<code>{{ yields.name }}</code>{% endif %}</td>{% endif %}
             <td>
               {% if yields.annotation %}
-                {% with expression = yields.annotation %}
+                {% with expression = yields.annotation, backlink_type = "yielded-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               {% endif %}
@@ -61,7 +61,7 @@ Context:
         <li class="doc-section-item field-body">
           {% if yields.name %}<b><code>{{ yields.name }}</code></b>{% endif %}
           {% if yields.annotation %}
-            {% with expression = yields.annotation %}
+            {% with expression = yields.annotation, backlink_type = "yielded-by" %}
               {% if yields.name %} ({% endif %}
               <code>{% include "expression"|get_template with context %}</code>
               {% if yields.name %}){% endif %}
@@ -93,7 +93,7 @@ Context:
                 <code>{{ yields.name }}</code>
               {% elif yields.annotation %}
                 <span class="doc-yields-annotation">
-                  {% with expression = yields.annotation %}
+                  {% with expression = yields.annotation, backlink_type = "yielded-by" %}
                     <code>{% include "expression"|get_template with context %}</code>
                   {% endwith %}
                 </span>
@@ -107,7 +107,7 @@ Context:
                 <p>
                   <span class="doc-yields-annotation">
                     <b>{{ lang.t("TYPE:") }}:</b>
-                    {% with expression = yields.annotation %}
+                    {% with expression = yields.annotation, backlink_type = "yielded-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja

@@ -11,7 +11,7 @@ which is a tree-like structure representing a Python expression.
   -#}
 {% endblock logs %}
 
-{%- macro crossref(name, annotation_path) -%}
+{%- macro crossref(name, annotation_path, backlink_type="") -%}
   {#- Output a cross-reference.
 
   This macro outputs a cross-reference to the given name.
@@ -35,11 +35,11 @@ which is a tree-like structure representing a Python expression.
       {{ prefix }}
       {%- if not signature -%}
         {#- Always render cross-references outside of signatures. We don't need to stash them. -#}
-        <autoref identifier="{{ path }}" optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
+        <autoref identifier="{{ path }}"{% if backlink_type %} backlink-type="{{ backlink_type }}" backlink-anchor="{{ html_id }}"{% endif %} optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
       {%- elif config.signature_crossrefs -%}
         {#- We're in a signature and cross-references are enabled, we must render one and stash it. -#}
         {%- filter stash_crossref(length=title|length) -%}
-          <autoref identifier="{{ path }}" optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
+          <autoref identifier="{{ path }}"{% if backlink_type %} backlink-type="{{ backlink_type }}" backlink-anchor="{{ html_id }}"{% endif %} optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
         {%- endfilter -%}
       {%- else -%}
         {#- We're in a signature but cross-references are disabled, we just render the title. -#}
@@ -72,7 +72,7 @@ which is a tree-like structure representing a Python expression.
   {%- endif -%}
 {%- endmacro -%}
 
-{%- macro render(expression, annotations_path) -%}
+{%- macro render(expression, annotations_path, backlink_type="") -%}
   {#- Render an expression.
 
   Parameters:
@@ -85,13 +85,13 @@ which is a tree-like structure representing a Python expression.
   {%- if expression is string -%}
     {%- if signature -%}{{ expression|safe }}{%- else -%}{{ expression }}{%- endif -%}
   {%- elif expression.classname == "ExprName" -%}
-    {{ crossref(expression, annotations_path) }}
+    {{ crossref(expression, annotations_path, backlink_type) }}
   {%- elif config.unwrap_annotated and expression.classname == "ExprSubscript" and expression.canonical_path in ("typing.Annotated", "typing_extensions.Annotated") -%}
     {{ render(expression.slice.elements[0], annotations_path) }}
   {%- elif expression.classname == "ExprAttribute" -%}
     {%- if annotations_path == "brief" -%}
       {%- if expression.last.is_enum_value -%}
-        {{ crossref(expression.last.parent, "brief") }}.value
+        {{ crossref(expression.last.parent, "brief", backlink_type) }}.value
       {%- else -%}
         {{ render(expression.last, "brief") }}
       {%- endif -%}
@@ -116,4 +116,4 @@ which is a tree-like structure representing a Python expression.
   {%- endif -%}
 {%- endmacro -%}
 
-{{ render(expression, config.annotations_path) }}
+{{ render(expression, config.annotations_path, backlink_type|default("")) }}

{mkdocstrings_python-1.16.4 → mkdocstrings_python-1.16.5}/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja

@@ -129,6 +129,10 @@ Context:
           {% endwith %}
         {% endblock docstring %}
 
+        {% if config.backlinks %}
+          <backlinks identifier="{{ html_id }}" handler="python" />
+        {% endif %}
+
         {% block source scoped %}
           {#- Source block.