feat: Support PEP 695 generics

PR-221: #221
Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>

Author: viccie30

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
     - name: Setup Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.12"
+        python-version: "3.13"
 
     - name: Setup uv
       uses: astral-sh/setup-uv@v5

docs/snippets/package/generics.py

@@ -0,0 +1,49 @@
+"""Some module showing generics.
+
+Type Aliases:
+    SomeType: Some type alias.
+"""
+
+type SomeType[Z] = int | list[Z]
+"""Some type alias.
+
+Type parameters:
+    Z: Some type parameter.
+"""
+
+
+class MagicBag[T: (str, bytes) = str](list[T]):
+    """A magic bag of items.
+
+    Type parameters:
+        T: Some type.
+    """
+
+    def __init__[U: (int, bool)](self, *args: T, flag1: U | None = None, flag2: U | None = None) -> None:
+        """Initialize bag.
+
+        Type parameters:
+            U: Some flag type.
+
+        Parameters:
+            flag1: Some flag.
+            flag2: Some flag.
+        """
+        super().__init__(args)
+        self.flag1 = flag1
+        self.flag2 = flag2
+
+    def mutate[K](self, item: T, into: K) -> K:
+        """Shake the bag to mutate an item into something else (and eject it).
+
+        Type parameters:
+            K: Some other type.
+
+        Parameters:
+            item: The item to mutate.
+            into: Mutate the item into something like this.
+
+        Returns:
+            The mutated item.
+        """
+        ...

docs/usage/configuration/docstrings.md

@@ -623,7 +623,7 @@ class ClassWithoutDocstring:
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Attributes" sections of docstrings.
+Whether to render the "Attributes" section of docstrings.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -676,7 +676,7 @@ class Class:
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Functions" or "Methods" sections of docstrings.
+Whether to render the "Functions" or "Methods" section of docstrings.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -751,7 +751,7 @@ class Class:
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Classes" sections of docstrings.
+Whether to render the "Classes" section of docstrings.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -804,13 +804,71 @@ class Class:
 ////
 ///
 
+[](){#option-show_docstring_type_aliases}
+## `show_docstring_type_aliases`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+
+Whether to render the "Type Aliases" section of docstrings.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_docstring_type_aliases: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      show_docstring_type_aliases: false
+```
+
+```python
+"""Summary.
+
+Type Aliases:
+    TypeAlias: Some type alias.
+"""
+
+
+type TypeAlias = int
+"""Summary."""
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With type_aliases
+<h2>module</h2>
+<p>Summary.</p>
+<p><b>Type Aliases:</b></p>
+
+**Name**     | **Description**
+------------ | ----------------
+`TypeAlias`  | Some type alias.
+
+<h3><code>TypeAlias</code></h3>
+<p>Summary.</p>
+////
+
+//// tab | Without classes
+<h2>module</h2>
+<p>Summary.</p>
+<h3><code>TypeAlias</code></h3>
+<p>Summary.</p>
+////
+///
+
 [](){#option-show_docstring_modules}
 ## `show_docstring_modules`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Modules" sections of docstrings.
+Whether to render the "Modules" section of docstrings.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -1245,6 +1303,57 @@ def rand() -> int:
 ////
 ///
 
+[](){#option-show_docstring_type_parameters}
+## `show_docstring_type_parameters`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to render the "Type Parameters" section of docstrings.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_docstring_type_parameters: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      show_docstring_type_parameters: false
+```
+
+```python
+class AClass[X: (int, str) = str]:
+    """Represents something.
+
+    Type Parameters:
+        X: Something.
+    """
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With parameters
+<h2><code>AClass</code></h2>
+<p>Represents something.</p>
+<p><b>Type Parameters:</b></p>
+
+**Name**   | **Bound or Constraints** | **Description** | **Default**
+---------- | ------------------------ | --------------- | -----------
+`whatever` | `(int, str)`             | Something.      | `str`
+////
+
+//// tab | Without parameters
+<h2><code>AClass</code></h2>
+<p>Represents something.</p>
+////
+///
+
 [](){#option-show_docstring_warns}
 ## `show_docstring_warns`
 

docs/usage/configuration/headings.md

@@ -682,3 +682,131 @@ NOTE: **Use with/without `heading`.** If you use this option without specifying
       heading: "My fancy module"
       toc_label: "My fancy module"
 ```
+
+[](){#option-type_parameter_headings}
+## `type_parameter_headings`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+
+Whether to render headings for generic class, function/method and type alias
+type parameters.
+
+With this option enabled, each type parameter of a generic object (including
+type parameters of `__init__` methods merged in their parent class with the
+[`merge_init_into_class`][] option) gets a permalink, an entry in the Table of
+Contents, and an entry in the generated objects inventory. The permalink and
+inventory entry allow cross-references from internal and external pages.
+
+<!-- TODO: Update when https://github.com/mkdocstrings/griffe/issues/404 is solved.
+The identifier used in the permalink and inventory is of the following form:
+`path.to.function:type_param_name`. To manually cross-reference a parameter,
+you can therefore use this Markdown syntax:
+
+```md
+- Class type parameter: [`Param`][package.module.Class[Param\]]
+- Method type parameter: [`Param`][package.module.Class.method[Param\]]
+- Function type parameter: [`Param`][package.module.function[Param\]]
+- Type alias type parameter: [`Param`][package.module.TypeAlias[Param\]]
+- Type variable tuple: [`*Args`][package.module.function[*Args\]]
+- Parameter specification: [`**Params`][package.module.function[**Params\]]
+```
+-->
+
+Enabling this option along with [`signature_crossrefs`][] will automatically
+render cross-references to type parameters in class/function/method/type alias
+signatures.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          type_parameter_headings: false
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      type_parameter_headings: true
+```
+
+/// admonition | Preview: Cross-references
+    type: preview
+
+```md exec="on"
+::: package.generics
+    options:
+      show_root_heading: false
+      heading_level: 3
+      docstring_section_style: list
+      show_bases: true
+      summary: false
+      separate_signature: true
+      show_signature_type_parameters: true
+      type_parameter_headings: true
+```
+
+///
+
+/// admonition | Preview: Type parameter sections
+    type: preview
+
+//// tab | Table style
+```md exec="on"
+::: package.generics.MagicBag
+    options:
+      members: false
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: table
+      show_docstring_description: false
+      show_docstring_parameters: false
+      show_docstring_returns: false
+```
+////
+
+//// tab | List style
+```md exec="on"
+::: package.generics.MagicBag
+    options:
+      members: false
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: list
+      show_docstring_description: false
+      show_docstring_parameters: false
+      show_docstring_returns: false
+```
+////
+
+//// tab | Spacy style
+```md exec="on"
+::: package.generics.MagicBag
+    options:
+      members: false
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: spacy
+      show_docstring_description: false
+      show_docstring_parameters: false
+      show_docstring_returns: false
+```
+////
+///
+
+/// admonition | Preview: Table of contents (with symbol types)
+    type: preview
+
+<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> mutate<br>
+<code class="doc-symbol doc-symbol-toc doc-symbol-type_parameter" style="margin-left: 16px;"></code> U
+
+To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
+
+///

docs/usage/configuration/members.md

@@ -585,7 +585,7 @@ package
 Whether to render summaries of modules, classes, functions (methods) and attributes.
 
 This option accepts a boolean (`yes`, `true`, `no`, `false` in YAML)
-or a dictionary with one or more of the following keys: `attributes`, `functions`, `classes`, `modules`,
+or a dictionary with one or more of the following keys: `attributes`, `functions`, `classes`, `modules`, `type_aliases`,
 with booleans as values. Class methods summary is (de)activated with the `functions` key.
 By default, `summary` is false, and by extension all values are false.