feat: Release inheritance diagram features

Author: pawamoy

docs/usage/configuration/general.md

@@ -269,6 +269,143 @@ plugins:
 
 WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `force_inspection` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards.
 
+[](){#option-inheritance_diagram_direction}
+## `inheritance_diagram_direction`
+
+The direction of the Mermaid chart presenting the inheritance diagram of a class, `TD` by default.
+
+```yaml title="mkdocs.yml"
+extra_javascript:
+- https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js
+```
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          inheritance_diagram_direction: TD
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.object
+    options:
+      inheritance_diagram_direction: TD
+```
+
+/// admonition | Preview
+    type: preview
+
+
+With the following classes:
+
+```python
+class SuperAbstract:
+    """Super abstract class."""
+class Mixin1:
+    """Mixin 1."""
+class Abstract(SuperAbstract, Mixin1):
+    """Abstract class."""
+class Mixin2A:
+    """Mixin 2A."""
+class Mixin2B(Mixin2A):
+    """Mixin 2B."""
+class Concrete(Abstract, Mixin2B):
+    """Concrete class."""
+class SuperConcrete(Concrete):
+    """Super concrete class."""
+```
+
+//// tab | `TD` (or `TB`)
+
+```mermaid
+flowchart TD
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+////
+
+//// tab | `BT`
+
+```mermaid
+flowchart BT
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+////
+
+//// tab | `RL`
+
+```mermaid
+flowchart RL
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+////
+
+//// tab | `LR`
+
+```mermaid
+flowchart LR
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+////
+///
+
 [](){#option-preload_modules}
 ## `preload_modules`
 

src/mkdocstrings_handlers/python/_internal/config.py

@@ -560,6 +560,14 @@ class PythonInputOptions:
         ),
     ] = 2
 
+    inheritance_diagram_direction: Annotated[
+        Literal["TB", "TD", "BT", "RL", "LR"],
+        _Field(
+            group="docstrings",
+            description="The direction of the Mermaid chart presenting the inheritance diagram of a class.",
+        ),
+    ] = "TD"
+
     inherited_members: Annotated[
         bool | list[str],
         _Field(

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

@@ -157,6 +157,54 @@ Context:
           {% endif %}
         {% endblock bases %}
 
+        {% block inheritance_diagram scoped %}
+          {#- Inheritance diagram block.
+          
+          This block renders the inheritance diagram for the class,
+          using Mermaid syntax and a bit of JavaScript to make the nodes clickable,
+          linking to the corresponding class documentation.
+          -#}
+          {% if config.show_inheritance_diagram and class.bases %}
+            {% macro edges(class) %}
+              {% for base in class.resolved_bases %}
+                {{ base.path }} --> {{ class.path }}
+                {{ edges(base) }}
+              {% endfor %}
+            {% endmacro %}
+            <div style="display: none">
+              <autoref identifier="{{ class.path }}" optional id="mermaid-link-{{ class.path }}"></autoref>
+                {% for base in class.mro() %}
+                  <autoref identifier="{{ base.path }}" optional id="mermaid-link-{{ base.path }}"></autoref>
+                {% endfor %}
+            </div>
+            <pre class="mermaid"><code id="mermaid-diagram-{{ class.path }}">
+              flowchart {{ config.inheritance_diagram_direction }}
+              {{ class.path }}[{{ class.name }}]
+              {% for base in class.mro() %}
+              {{ base.path }}[{{ base.name }}]
+              {% endfor %}
+
+              {{ edges(class) | safe }}
+
+              click {{ class.path }} href "" "{{ class.path }}"
+              {% for base in class.mro() %}
+              click {{ base.path }} href "" "{{ base.path }}"
+              {% endfor %}
+            </code></pre>
+            <script>
+              var diagram = document.getElementById('mermaid-diagram-{{ class.path }}');
+              diagram.innerHTML = diagram.innerHTML.replace(/click ([\w.]+) href "" "\1"/g, function(match, nodeID, offset) {
+                try {
+                  const link = document.getElementById("mermaid-link-" + nodeID).href;
+                  return `click ${nodeID} href "${link}" "${nodeID}"`
+                } catch (e) {
+                  return '';
+                }
+              });
+            </script>
+          {% endif %}
+        {% endblock inheritance_diagram %}
+
         {% block docstring scoped %}
           {#- Docstring block.
 

src/mkdocstrings_handlers/python/templates/readthedocs/_base/class.html

@@ -0,0 +1,11 @@
+{% extends "_base/class.html.jinja" %}
+
+{% block logs scoped %}
+  {{ super() }}
+  {# TODO: Switch to a warning after some time. #}
+  {{ log.info(
+        "DeprecationWarning: Extending '_base/class.html' is deprecated, extend '_base/class.html.jinja' instead. " ~
+        "After some time, this message will be logged as a warning, causing strict builds to fail.",
+        once=True,
+      ) }}
+{% endblock logs %}