feat: Release backlinks feature

Author: pawamoy

src/mkdocstrings_handlers/python/_internal/handler.py

@@ -22,15 +22,17 @@
     patch_loggers,
 )
 from mkdocs.exceptions import PluginError
+from mkdocs_autorefs import BacklinkCrumb
 from mkdocstrings import BaseHandler, CollectionError, CollectorItem, HandlerOptions, Inventory, get_logger
 
 from mkdocstrings_handlers.python._internal import rendering
 from mkdocstrings_handlers.python._internal.config import PythonConfig, PythonOptions
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Mapping, MutableMapping, Sequence
+    from collections.abc import Iterable, Iterator, Mapping, MutableMapping, Sequence
 
     from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs_autorefs import Backlink
 
 
 # YORE: EOL 3.10: Replace block with line 2.
@@ -306,6 +308,24 @@ def render(self, data: CollectorItem, options: PythonOptions, locale: str | None
             },
         )
 
+    def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]], *, locale: str | None = None) -> str:  # noqa: ARG002
+        """Render the backlinks.
+
+        Parameters:
+            backlinks: The backlinks to render.
+
+        Returns:
+            The rendered backlinks (HTML).
+        """
+        template = self.env.get_template("backlinks.html.jinja")
+        verbose_type = {key: key.capitalize().replace("-by", " by") for key in backlinks.keys()}  # noqa: SIM118
+        return template.render(
+            backlinks=backlinks,
+            config=self.get_options({}),
+            verbose_type=verbose_type,
+            default_crumb=BacklinkCrumb(title="", url=""),
+        )
+
     def update_env(self, config: Any) -> None:  # noqa: ARG002
         """Update the Jinja environment with custom filters and tests.
 

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

@@ -15,3 +15,52 @@ Context:
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
 {% endblock logs %}
+
+{% macro render_crumb(crumb, last=false) %}
+  <span class="doc doc-backlink-crumb{{ " last" if last else "" }}">
+    {% if crumb.url and crumb.title %}
+      <a href="{{ crumb.url }}">{{ crumb.title | safe }}</a>
+    {% elif crumb.title %}
+      <span>{{ crumb.title | safe }}</span>
+    {% endif %}
+  </span>
+{% endmacro %}
+
+{% macro render_tree(tree) %}
+  <ul class="doc doc-backlink-list">
+    {% for node, child in tree | dictsort %}
+      <li class="doc doc-backlink">
+        {% for crumb in node %}
+          {{ render_crumb(crumb, last=loop.last and not child) }}
+        {% endfor %}
+        {% if child %}
+          {{ render_tree(child) }}
+        {% endif %}
+      </li>
+    {% endfor %}
+  </ul>
+{% endmacro %}
+
+{% if config.backlinks %}
+  <div class="doc doc-backlinks">
+    {% if config.backlinks == "tree" %}
+      {% for backlink_type, backlink_list in backlinks | dictsort %}
+        <b class="doc doc-backlink-type">{{ verbose_type[backlink_type] }}:</b>
+        {{ render_tree(backlink_list|backlink_tree) }}
+      {% endfor %}
+    {% elif config.backlinks == "flat" %}
+      {% 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 %}
+                {{ render_crumb(crumb, last=loop.last) }}
+              {% endfor %}
+            </li>
+          {% endfor %}
+        </ul>
+      {% endfor %}
+    {% endif %}
+  </div>
+{% endif %}