feat: Support backlinks

Issue-153: #153
mkdocstrings · Feb 24, 2025 · e810784 · e810784
1 parent 15a7009
commit e810784
Show file tree

Hide file tree

Showing 25 changed files with 139 additions and 54 deletions.
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterable
 import glob
 import os
 import posixpath
@@ -33,6 +34,7 @@
     from collections.abc import Iterator, Mapping, MutableMapping, Sequence
 
     from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs_autorefs.plugin import Backlink
 
 
 if sys.version_info >= (3, 11):
@@ -280,6 +282,11 @@ def render(self, data: CollectorItem, options: PythonOptions) -> str:  # noqa: D
             },
         )
 
+    def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]]) -> str:  # noqa: D102 (ignore missing docstring)
+        template = self.env.get_template("backlinks.html.jinja")
+        verbose_type = {key: key.capitalize().replace("-by", " by") for key in backlinks.keys()}
+        return template.render(backlinks=backlinks, config=self.get_options({}), verbose_type=verbose_type)
+
     def update_env(self, config: Any) -> None:  # noqa: ARG002
         """Update the Jinja environment with custom filters and tests.
 

diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py
@@ -210,10 +210,10 @@ 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)

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja
@@ -113,6 +113,8 @@ Context:
             {% include "docstring"|get_template with context %}
           {% endwith %}
         {% endblock docstring %}
+
+        <backlinks identifier="{{ html_id }}" handler="python" />
       {% endblock contents %}
     </div>
 

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/backlinks.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/backlinks.html.jinja
@@ -0,0 +1,37 @@
+{#- Template for backlinks.
+
+This template renders backlinks.
+
+Context:
+  backlinks (Mapping[str, Iterable[str]]): The backlinks to render.
+  config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+  {{ log.debug("Rendering backlinks") }}
+{% endblock logs %}
+
+<div class="doc doc-backlinks">
+  {% for backlink_type, backlink_list in backlinks | dictsort %}
+    <b class="doc doc-backlink-type">{{ verbose_type[backlink_type] }}:</b>
+    <ul class="doc doc-backlink-list">
+      {% for backlink in backlink_list | sort(attribute="crumbs") %}
+        <li class="doc doc-backlink">
+          {% for crumb in backlink.crumbs %}
+            <span class="doc doc-backlink-crumb">
+              {% if crumb.url and crumb.title %}
+                <a href="{{ crumb.url }}">{{ crumb.title | safe }}</a>
+              {% elif crumb.title %}
+                <span>{{ crumb.title | safe }}</span>
+              {% endif %}
+            </span>
+          {% endfor %}
+        </li>
+      {% endfor %}
+    </ul>
+  {% endfor %}
+</div>
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/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,8 @@ Context:
           {% endif %}
         {% endblock docstring %}
 
+        <backlinks identifier="{{ html_id }}" handler="python" />
+
         {% block summary scoped %}
           {#- Summary block.
 

diff --git a/...docstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja b/...docstrings_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>

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja b/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,15 +149,15 @@ 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>
                 {% endif %}
                 {% 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>

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja b/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>

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html.jinja b/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>

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html.jinja b/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>

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html.jinja b/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>

diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html.jinja b/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>