fixup! refactor: Add backlinks metadata to autorefs elements

Author: pawamoy

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
@@ -268,6 +269,11 @@ def render(self, data: CollectorItem, options: PythonOptions) -> str:  # noqa: D
             },
         )
 
+    def render_backlinks(self, backlinks: Mapping[str, Iterable[str]]) -> 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.
 

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, reftype="returned-by")
+        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, reftype="used-by")
+        value = template.render(context.parent, expression=attribute.value, signature=True, backlink_type="used-by")
         signature += f" = {value}"
 
     signature = do_format_code(signature, line_length)

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

@@ -12,7 +12,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering " + attribute.path) }}
@@ -44,7 +44,7 @@ Context:
 
         {% block heading scoped %}
           {#- Heading block.
-          
+
           This block renders the heading for the attribute.
           -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
@@ -60,7 +60,7 @@ Context:
 
         {% block labels scoped %}
           {#- Labels block.
-          
+
           This block renders the labels for the attribute.
           -#}
           {% with labels = attribute.labels %}
@@ -72,7 +72,7 @@ Context:
 
       {% block signature scoped %}
         {#- Signature block.
-        
+
         This block renders the signature for the attribute.
         -#}
         {% if config.separate_signature %}
@@ -99,20 +99,22 @@ Context:
     <div class="doc doc-contents {% if root %}first{% endif %}">
       {% block contents scoped %}
         {#- Contents block.
-        
+
         This block renders the contents of the attribute.
         It contains other blocks that users can override.
         Overriding the contents block allows to rearrange the order of the blocks.
         -#}
         {% block docstring scoped %}
           {#- Docstring block.
-          
+
           This block renders the docstring for the attribute.
           -#}
           {% with docstring_sections = attribute.docstring.parsed %}
             {% include "docstring"|get_template with context %}
           {% endwith %}
         {% endblock docstring %}
+
+        <backlinks identifier="{{ html_id }}" handler="python" />
       {% endblock contents %}
     </div>
 

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

@@ -0,0 +1,27 @@
+{#- 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 url, title in backlink_list | sort(attribute=1) %}
+        <li><a href="{{ url }}" class="doc doc-backlink">{{ (title or url.split("#", 1)[-1]) | safe }}</a></li>
+      {% endfor %}
+    </ul>
+  {% endfor %}
+</div>

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

@@ -11,7 +11,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering " + class.path) }}
@@ -37,13 +37,14 @@ Context:
           heading_level,
           role="class",
           id=html_id,
+          title=html_id,
           class="doc doc-heading",
           toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + class.name,
         ) %}
 
         {% block heading scoped %}
           {#- Heading block.
-          
+
           This block renders the heading for the class.
           -#}
           {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>{% endif %}
@@ -62,7 +63,7 @@ Context:
 
         {% block labels scoped %}
           {#- Labels block.
-          
+
           This block renders the labels for the class.
           -#}
           {% with labels = class.labels %}
@@ -74,7 +75,7 @@ Context:
 
       {% block signature scoped %}
         {#- Signature block.
-        
+
         This block renders the signature for the class.
         Overloads of the `__init__` method are rendered if `merge_init_into_class` is enabled.
         The actual `__init__` method signature is only rendered if `separate_signature` is also enabled.
@@ -117,21 +118,21 @@ Context:
     <div class="doc doc-contents {% if root %}first{% endif %}">
       {% block contents scoped %}
         {#- Contents block.
-        
+
         This block renders the contents of the class.
         It contains other blocks that users can override.
         Overriding the contents block allows to rearrange the order of the blocks.
         -#}
         {% block bases scoped %}
           {#- Class bases block.
-          
+
           This block renders the bases for the class.
           -#}
           {% if config.show_bases and class.bases %}
             <p class="doc doc-class-bases">
               Bases: {% for expression in class.bases -%}
                 <code>
-                  {%- with reftype = "subclassed-by" -%}
+                  {%- with backlink_type = "subclassed-by" -%}
                     {%- include "expression"|get_template with context -%}
                   {%- endwith -%}
                 </code>{% if not loop.last %}, {% endif %}
@@ -142,7 +143,7 @@ Context:
 
         {% block docstring scoped %}
           {#- Docstring block.
-          
+
           This block renders the docstring for the class.
           -#}
           {% with docstring_sections = class.docstring.parsed %}
@@ -163,17 +164,19 @@ Context:
           {% endif %}
         {% endblock docstring %}
 
+        <backlinks identifier="{{ html_id }}" handler="python" />
+
         {% block summary scoped %}
           {#- Summary block.
-          
+
           This block renders auto-summaries for classes, methods, and attributes.
           -#}
           {% include "summary"|get_template with context %}
         {% endblock summary %}
 
         {% block source scoped %}
           {#- Source block.
-          
+
           This block renders the source code for the class.
           -#}
           {% if config.show_source %}
@@ -209,7 +212,7 @@ Context:
 
         {% block children scoped %}
           {#- Children block.
-          
+
           This block renders the children (members) of the class.
           -#}
           {% set root = False %}

src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja

@@ -9,7 +9,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering attributes section") }}
@@ -36,7 +36,7 @@ Context:
             <td><code><autoref identifier="{{ obj.path }}.{{ attribute.name }}" optional hover>{{ attribute.name }}</autoref></code></td>
             <td>
               {% if attribute.annotation %}
-                {% with expression = attribute.annotation, reftype = "returned-by" %}
+                {% with expression = attribute.annotation, backlink_type = "returned-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><autoref identifier="{{ obj.path }}.{{ attribute.name }}" optional hover>{{ attribute.name }}</autoref></code></b>
           {% if attribute.annotation %}
-            {% with expression = attribute.annotation, reftype = "returned-by" %}
+            {% with expression = attribute.annotation, backlink_type = "returned-by" %}
               (<code>{% include "expression"|get_template with context %}</code>)
             {% endwith %}
           {% endif %}
@@ -94,7 +94,7 @@ Context:
                 {% if attribute.annotation %}
                   <span class="doc-attribute-annotation">
                     <b>TYPE:</b>
-                    {% with expression = attribute.annotation, reftype = "returned-by" %}
+                    {% with expression = attribute.annotation, backlink_type = "returned-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

src/mkdocstrings_handlers/python/templates/material/_base/docstring/other_parameters.html.jinja

@@ -9,7 +9,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering other parameters section") }}
@@ -36,7 +36,7 @@ Context:
             <td><code>{{ parameter.name }}</code></td>
             <td>
               {% if parameter.annotation %}
-                {% with expression = parameter.annotation, reftype = "used-by" %}
+                {% 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, reftype = "used-by" %}
+            {% 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, reftype = "used-by" %}
+                    {% with expression = parameter.annotation, backlink_type = "used-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja

@@ -9,7 +9,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering parameters section") }}
@@ -51,7 +51,7 @@ Context:
             </td>
             <td>
               {% if parameter.annotation %}
-                {% with expression = parameter.annotation, reftype = "used-by" %}
+                {% 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, reftype = "used-by" %}
+                {% 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, reftype = "used-by" %}
+            {% 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, reftype = "used-by" %}
+                {% 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, reftype = "used-by" %}
+                    {% 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, reftype = "used-by" %}
+                    {% with expression = parameter.default, backlink_type = "used-by" %}
                       <code>{% include "expression"|get_template with context %}</code>
                     {% endwith %}
                   </span>

src/mkdocstrings_handlers/python/templates/material/_base/docstring/raises.html.jinja

@@ -9,7 +9,7 @@ Context:
 
 {% block logs scoped %}
   {#- Logging block.
-  
+
   This block can be used to log debug messages, deprecation messages, warnings, etc.
   -#}
   {{ log.debug("Rendering raises section") }}
@@ -34,7 +34,7 @@ Context:
           <tr class="doc-section-item">
             <td>
               {% if raises.annotation %}
-                {% with expression = raises.annotation, reftype = "raised-by" %}
+                {% 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, reftype = "raised-by" %}
+            {% 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, reftype = "raised-by" %}
+                {% with expression = raises.annotation, backlink_type = "raised-by" %}
                   <code>{% include "expression"|get_template with context %}</code>
                 {% endwith %}
               </span>