mkdocstrings-python 1.17.0__tar.gz → 1.18.0__tar.gz

{mkdocstrings_python-1.17.0 → mkdocstrings_python-1.18.0}/CHANGELOG.md

@@ -5,6 +5,18 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [1.18.0](https://github.com/mkdocstrings/python/releases/tag/1.18.0) - 2025-08-26
+
+<small>[Compare with 1.17.0](https://github.com/mkdocstrings/python/compare/1.17.0...1.18.0)</small>
+
+### Features
+
+- Support PEP 695 generics ([dc8c3ad](https://github.com/mkdocstrings/python/commit/dc8c3adb23b37add6601de9e74085f76e5fc9ee5) by Victor Westerhuis). [PR-221](https://github.com/mkdocstrings/python/pull/221), Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>
+
+### Bug Fixes
+
+- Increase maximum recursion limit in case of deeply nested ASTs (rare occurrence) ([6004ccf](https://github.com/mkdocstrings/python/commit/6004ccf3576c7a20e21c880bb2235b7b426ba382) by Timothée Mazzucotelli). [Issue-griffe-402](https://github.com/mkdocstrings/griffe/issues/402)
+
 ## [1.17.0](https://github.com/mkdocstrings/python/releases/tag/1.17.0) - 2025-08-14
 
 <small>[Compare with 1.16.12](https://github.com/mkdocstrings/python/compare/1.16.12...1.17.0)</small>

{mkdocstrings_python-1.17.0 → mkdocstrings_python-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-python
-Version: 1.17.0
+Version: 1.18.0
 Summary: A Python handler for mkdocstrings.
 Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
 License-Expression: ISC
@@ -32,7 +32,7 @@ Project-URL: Funding, https://github.com/sponsors/pawamoy
 Requires-Python: >=3.9
 Requires-Dist: mkdocstrings>=0.30
 Requires-Dist: mkdocs-autorefs>=1.4
-Requires-Dist: griffe>=1.12.1
+Requires-Dist: griffe>=1.13
 Requires-Dist: typing-extensions>=4.0; python_version < "3.11"
 Description-Content-Type: text/markdown
 

mkdocstrings_python-1.18.0/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.
+        """
+        ...

{mkdocstrings_python-1.17.0 → mkdocstrings_python-1.18.0}/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`
 

{mkdocstrings_python-1.17.0 → mkdocstrings_python-1.18.0}/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).
+
+///

{mkdocstrings_python-1.17.0 → mkdocstrings_python-1.18.0}/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.
 

{mkdocstrings_python-1.17.0 → mkdocstrings_python-1.18.0}/docs/usage/configuration/signatures.md

@@ -430,6 +430,61 @@ function(param1, param2=None)
 ////
 ///
 
+[](){#option-show_signature_type_parameters}
+## `show_signature_type_parameters`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Show the type parameters in generic classes, methods, functions and type aliases
+signatures.
+
+Since the heading can become quite long when type parameters are rendered, it is
+usually best to [separate the signature][separate_signature] from the heading.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          separate_signature: true
+          show_signature_annotations: true
+          show_signature_type_parameters: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      separate_signature: true
+      show_signature_annotations: true
+      show_signature_type_parameters: false
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With signature type parameters
+<h2>function</h2>
+
+```python
+function[T, *R](param: T) -> tuple[*R]
+```
+
+<p>Function docstring.</p>
+////
+
+//// tab | Without signature type parameters
+<h2>function</h2>
+
+```python
+function(param: T) -> tuple[*R]
+```
+
+<p>Function docstring.</p>
+////
+///
+
 [](){#option-separate_signature}
 ## `separate_signature`
 

{mkdocstrings_python-1.17.0 → mkdocstrings_python-1.18.0}/docs/usage/customization.md

@@ -34,9 +34,10 @@ The following CSS classes are used in the generated HTML:
     - `doc-class`: on `div`s containing a class
     - `doc-function`: on `div`s containing a function
     - `doc-module`: on `div`s containing a module
+    - `doc-type_alias`: on `div`s containing a type alias
 - `doc-heading`: on objects headings
     - `doc-object-name`: on `span`s wrapping objects names/paths in the heading
-        - `doc-KIND-name`: as above, specific to the kind of object (module, class, function, attribute)
+        - `doc-KIND-name`: as above, specific to the kind of object (module, class, function, attribute, type_alias)
 - `doc-contents`: on `div`s wrapping the docstring then the children (if any)
     - `first`: same, but only on the root object's contents `div`
 - `doc-labels`: on `span`s wrapping the object's labels
@@ -48,7 +49,7 @@ The following CSS classes are used in the generated HTML:
 - `doc-symbol`: on `code` tags of symbol types
     - `doc-symbol-heading`: on symbol types in headings
     - `doc-symbol-toc`: on symbol types in the ToC
-    - `doc-symbol-KIND`: specific to the kind of object (`module`, `class`, `function`, `method`, `attribute`)
+    - `doc-symbol-KIND`: specific to the kind of object (`module`, `class`, `function`, `method`, `attribute`, `type_alias`)
 
 /// admonition | Example with colorful labels
     type: example
@@ -90,33 +91,41 @@ by overriding the values of our CSS variables, for example:
 ```css title="docs/css/mkdocstrings.css"
 [data-md-color-scheme="default"] {
   --doc-symbol-parameter-fg-color: #df50af;
+  --doc-symbol-type_parameter-fg-color: #df50af;
   --doc-symbol-attribute-fg-color: #0079ff;
   --doc-symbol-function-fg-color: #00dfa2;
   --doc-symbol-method-fg-color: #00dfa2;
   --doc-symbol-class-fg-color: #d1b619;
+  --doc-symbol-type_alias-fg-color: #d1b619;
   --doc-symbol-module-fg-color: #ff0060;
 
   --doc-symbol-parameter-bg-color: #df50af1a;
+  --doc-symbol-type_parameter-bg-color: #df50af1a;
   --doc-symbol-attribute-bg-color: #0079ff1a;
   --doc-symbol-function-bg-color: #00dfa21a;
   --doc-symbol-method-bg-color: #00dfa21a;
   --doc-symbol-class-bg-color: #d1b6191a;
+  --doc-symbol-type_alias-bg-color: #d1b6191a;
   --doc-symbol-module-bg-color: #ff00601a;
 }
 
 [data-md-color-scheme="slate"] {
   --doc-symbol-parameter-fg-color: #ffa8cc;
+  --doc-symbol-type_parameter-fg-color: #ffa8cc;
   --doc-symbol-attribute-fg-color: #963fb8;
   --doc-symbol-function-fg-color: #6d67e4;
   --doc-symbol-method-fg-color: #6d67e4;
   --doc-symbol-class-fg-color: #46c2cb;
+  --doc-symbol-type_alias-fg-color: #46c2cb;
   --doc-symbol-module-fg-color: #f2f7a1;
 
   --doc-symbol-parameter-bg-color: #ffa8cc1a;
+  --doc-symbol-type_parameter-bg-color: #ffa8cc1a;
   --doc-symbol-attribute-bg-color: #963fb81a;
   --doc-symbol-function-bg-color: #6d67e41a;
   --doc-symbol-method-bg-color: #6d67e41a;
   --doc-symbol-class-bg-color: #46c2cb1a;
+  --doc-symbol-type_alias-bg-color: #46c2cb1a;
   --doc-symbol-module-bg-color: #f2f7a11a;
 }
 ```
@@ -129,17 +138,21 @@ otherwise just override the variables at root level:
 ```css title="docs/css/mkdocstrings.css"
 :root {
   --doc-symbol-parameter-fg-color: #df50af;
+  --doc-symbol-type_parameter-fg-color: #df50af;
   --doc-symbol-attribute-fg-color: #0079ff;
   --doc-symbol-function-fg-color: #00dfa2;
   --doc-symbol-method-fg-color: #00dfa2;
   --doc-symbol-class-fg-color: #d1b619;
+  --doc-symbol-type_alias-fg-color: #d1b619;
   --doc-symbol-module-fg-color: #ff0060;
 
   --doc-symbol-parameter-bg-color: #df50af1a;
+  --doc-symbol-type_parameter-bg-color: #df50af1a;
   --doc-symbol-attribute-bg-color: #0079ff1a;
   --doc-symbol-function-bg-color: #00dfa21a;
   --doc-symbol-method-bg-color: #00dfa21a;
   --doc-symbol-class-bg-color: #d1b6191a;
+  --doc-symbol-type_alias-bg-color: #d1b6191a;
   --doc-symbol-module-bg-color: #ff00601a;
 }
 ```
@@ -151,33 +164,41 @@ otherwise just override the variables at root level:
   <style>
     [data-md-color-scheme="default"] #preview-symbol-colors {
       --doc-symbol-parameter-fg-color: #df50af;
+      --doc-symbol-type_parameter-fg-color: #df50af;
       --doc-symbol-attribute-fg-color: #0079ff;
       --doc-symbol-function-fg-color: #00dfa2;
       --doc-symbol-method-fg-color: #00dfa2;
       --doc-symbol-class-fg-color: #d1b619;
+      --doc-symbol-type_alias-fg-color: #d1b619;
       --doc-symbol-module-fg-color: #ff0060;
 
       --doc-symbol-parameter-bg-color: #df50af1a;
+      --doc-symbol-type_parameter-bg-color: #df50af1a;
       --doc-symbol-attribute-bg-color: #0079ff1a;
       --doc-symbol-function-bg-color: #00dfa21a;
       --doc-symbol-method-bg-color: #00dfa21a;
       --doc-symbol-class-bg-color: #d1b6191a;
+      --doc-symbol-type_alias-bg-color: #d1b6191a;
       --doc-symbol-module-bg-color: #ff00601a;
     }
 
     [data-md-color-scheme="slate"] #preview-symbol-colors {
       --doc-symbol-parameter-fg-color: #ffa8cc;
+      --doc-symbol-type_parameter-fg-color: #ffa8cc;
       --doc-symbol-attribute-fg-color: #963fb8;
       --doc-symbol-function-fg-color: #6d67e4;
       --doc-symbol-method-fg-color: #6d67e4;
       --doc-symbol-class-fg-color: #46c2cb;
+      --doc-symbol-type_alias-fg-color: #46c2cb;
       --doc-symbol-module-fg-color: #f2f7a1;
 
       --doc-symbol-parameter-bg-color: #ffa8cc1a;
+      --doc-symbol-type_parameter-bg-color: #ffa8cc1a;
       --doc-symbol-attribute-bg-color: #963fb81a;
       --doc-symbol-function-bg-color: #6d67e41a;
       --doc-symbol-method-bg-color: #6d67e41a;
       --doc-symbol-class-bg-color: #46c2cb1a;
+      --doc-symbol-type_alias-bg-color: #46c2cb1a;
       --doc-symbol-module-bg-color: #f2f7a11a;
     }
   </style>
@@ -204,6 +225,10 @@ For example, to use single letters instead of truncated types:
   content: "P";
 }
 
+.doc-symbol-type_parameter::after {
+  content: "P";
+}
+
 .doc-symbol-attribute::after {
   content: "A";
 }
@@ -220,6 +245,10 @@ For example, to use single letters instead of truncated types:
   content: "C";
 }
 
+.doc-symbol-type_alias::after {
+  content: "T";
+}
+
 .doc-symbol-module::after {
   content: "M";
 }
@@ -234,6 +263,10 @@ For example, to use single letters instead of truncated types:
       content: "P";
     }
 
+    #preview-symbol-names .doc-symbol-type_parameter::after {
+      content: "P";
+    }
+
     #preview-symbol-names .doc-symbol-attribute::after {
       content: "A";
     }
@@ -250,16 +283,22 @@ For example, to use single letters instead of truncated types:
       content: "C";
     }
 
+    #preview-symbol-names .doc-symbol-type_alias::after {
+      content: "T";
+    }
+
     #preview-symbol-names .doc-symbol-module::after {
       content: "M";
     }
   </style>
   <ul>
     <li>Parameter: <code class="doc-symbol doc-symbol-parameter"></code></li>
+    <li>Type Parameter: <code class="doc-symbol doc-symbol-type_parameter"></code></li>
     <li>Attribute: <code class="doc-symbol doc-symbol-attribute"></code></li>
     <li>Function: <code class="doc-symbol doc-symbol-function"></code></li>
     <li>Method: <code class="doc-symbol doc-symbol-method"></code></li>
     <li>Class: <code class="doc-symbol doc-symbol-class"></code></li>
+    <li>Type Alias: <code class="doc-symbol doc-symbol-type_alias"></code></li>
     <li>Module: <code class="doc-symbol doc-symbol-module"></code></li>
   </ul>
 </div>
@@ -324,6 +363,19 @@ Available context:
 - `config`: The handler configuration (dictionary).
 - `module`: The [Module][griffe.Module] instance.
 
+#### `type_alias.html`
+
+- `heading`: The class heading.
+- `labels`: The class labels.
+- `signature`: The class signature.
+- `contents`: The class contents: bases, docstring, source and children blocks.
+- `docstring`: The class docstring.
+
+Available context:
+
+- `config`: The handler configuration (dictionary).
+- `type_alias`: The [TypeAlias][griffe.TypeAlias] instance.
+
 #### `class.html`
 
 - `heading`: The class heading.
@@ -379,6 +431,8 @@ In `docstring/attributes.html`,
 `docstring/raises.html`,
 `docstring/receives.html`,
 `docstring/returns.html`,
+`docstring/type_aliases.html`,
+`docstring/type_parameters.html`,
 `docstring/warns.html`,
 and `docstring/yields.html`:
 

{mkdocstrings_python-1.17.0 → mkdocstrings_python-1.18.0}/duties.py

@@ -93,7 +93,7 @@ def check_quality(ctx: Context) -> None:
     )
 
 
-@duty
+@duty(skip_if=sys.version_info < (3, 13), skip_reason=pyprefix("Skipped: docs require modern generics syntax"))
 def check_docs(ctx: Context) -> None:
     """Check if the documentation builds correctly."""
     Path("htmlcov").mkdir(parents=True, exist_ok=True)
@@ -128,7 +128,7 @@ def check_api(ctx: Context, *cli_args: str) -> None:
     )
 
 
-@duty
+@duty(skip_if=sys.version_info < (3, 13), skip_reason=pyprefix("Skipped: docs require modern generics syntax"))
 def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000) -> None:
     """Serve the documentation (localhost:8000).
 
@@ -144,7 +144,7 @@ def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000
         )
 
 
-@duty
+@duty(skip_if=sys.version_info < (3, 13), skip_reason=pyprefix("Skipped: docs require modern generics syntax"))
 def docs_deploy(ctx: Context, *, force: bool = False) -> None:
     """Deploy the documentation to GitHub pages.