Summary.
+Type Aliases:
+ +**Name** | **Description** +------------ | ---------------- +`TypeAlias` | Some type alias. + +TypeAliasSummary.
+//// + +//// tab | Without classes +Summary.
+TypeAliasSummary.
+//// +/// + ## `show_docstring_modules` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** @@ -1225,6 +1282,56 @@ def rand() -> int: //// /// +## `show_docstring_type_parameters` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +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 +AClassRepresents something.
+Type Parameters:
+ +**Name** | **Bound or Constraints** | **Description** | **Default** +---------- | ------------------------ | --------------- | ----------- +`whatever` | `(int, str)` | Something. | `str` +//// + +//// tab | Without parameters +AClassRepresents something.
+//// +/// + ## `show_docstring_warns` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index 467779e4..511650ff 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -179,6 +179,285 @@ To customize symbols, see [Customizing symbol types](../customization.md/#symbol /// +## `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. + +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 + +Parameters:
+Type Parameters:
+| Name | +Bound or Constraints | +Description | +Default | +
|---|---|---|---|
+
+ |
+ + | +
+
+
+ The type of the element. + |
+ + required + | +
Function docstring.
+//// + +//// tab | Without signature type parameters +Function docstring.
+//// +/// + ## `separate_signature` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 907809c8..7f9dc2c6 100644 --- a/docs/usage/customization.md +++ b/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: @@ -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,23 @@ 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"; }{{ class_name }}
+ {%+ filter highlight(language="python", inline=True) %}
+ {{ class_name }}{% include "type_parameters"|get_template with context %}
+ {% endfilter %}
{% endif %}
{% endblock heading %}
{% block labels scoped %}
{#- Labels block.
-
+
This block renders the labels for the class.
-#}
{% with labels = class.labels %}
@@ -74,30 +84,39 @@ 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.
+
+ If the class is generic, but the `__init__` method isn't or `merge_init_into_class` is disabled,
+ the class signature is rendered if `separate_signature` and `show_signature_type_parameters` are enabled.
+
+ If the `__init__` method or any overloads are generic, they are rendered as methods if
+ `merge_init_into_class`, `separate_signature` and `show_signature_type_parameters` are enabled.
-#}
- {% if config.merge_init_into_class %}
- {% if "__init__" in all_members %}
- {% with function = all_members["__init__"] %}
- {% if function.overloads %}
- {{ section.title or lang.t("Type Aliases:") }}
+| {{ lang.t("Name") }} | +{{ lang.t("Description") }} | +
|---|---|
|
+
+
+ {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Type Aliases:") }}
+{{ type_alias.name }} | {{ (section.title or lang.t("TYPE ALIAS")).rstrip(":").upper() }} | +{{ lang.t("DESCRIPTION") }} | +
|---|---|
|
+
+
+ {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
{{ section.title or lang.t("Type Parameters:") if not is_merged_init else lang.t("__init__ Type Parameters:") }}
| {{ lang.t("Name") }} | +{{ lang.t("Bound or Constraints") }} | +{{ lang.t("Description") }} | +{{ lang.t("Default") }} | +
|---|---|---|---|
+ {% if config.type_parameter_headings %}
+ {% filter heading(
+ heading_level + 1,
+ role="typeparam",
+ id=obj.path ~ ":" ~ type_parameter.name,
+ class="doc doc-heading doc-heading-type_parameter",
+ toc_label=('{{ type_parameter.name }}
+ {% endfilter %}
+ {% else %}
+ {{ type_parameter.name }}
+ {% endif %}
+ |
+
+ {% if type_parameter.annotation %}
+ {% with expression = type_parameter.annotation %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %}
+ |
+
+
+ {{ type_parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+ |
+
+ {% if type_parameter.default %}
+ {% with expression = type_parameter.default %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% else %}
+ {{ lang.t("required") }}
+ {% endif %}
+ |
+
{{ section.title or lang.t("Type Parameters:") if not is_merged_init else lang.t("__init__ Type Parameters:") }}
{{ type_parameter.name }}
+ {% endfilter %}
+ {% else %}
+ {{ type_parameter.name }}
+ {% endif %}
+ {% if type_parameter.annotation %}
+ (
+ {%- if type_parameter.constraints -%}
+ {%- for expression in type_parameter.constraints -%}
+ {% include "expression"|get_template with context %}
+ {%- if not loop.last %}, {% endif -%}
+ {%- endfor -%}
+ {%- else -%}
+ {%- with expression = type_parameter.bound -%}
+ {% include "expression"|get_template with context %}
+ {%- endwith -%}
+ {%- endif -%}
+ {%- if type_parameter.default %}, {{ lang.t("default:") }}
+ {% with expression = type_parameter.default %}
+ {% include "expression"|get_template with context %}
+ {% endwith %}
+ {% endif %})
+ {% endif %}
+ –
+ {{ (section.title or lang.t("TYPE PARAMETER")).rstrip(":").upper() if not is_merged_init else lang.t("__init__ TYPE PARAMETER") }} |
+ {{ lang.t("DESCRIPTION") }} | +
|---|---|
+ {% if config.type_parameter_headings %}
+ {% filter heading(
+ heading_level + 1,
+ role="typeparam",
+ id=obj.path ~ ":" ~ type_parameter.name ,
+ class="doc doc-heading doc-heading-type_parameter",
+ toc_label=('{{ type_parameter.name }}
+ {% endfilter %}
+ {% else %}
+ {{ type_parameter.name }}
+ {% endif %}
+ |
+
+
+ {{ type_parameter.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+
+
+ {% if type_parameter.constraints %}
+
+ {{ lang.t("CONSTRAINTS:") }}
+ {% for constraint in type_parameter.constraints -%}
+ {%- with expression = constraint -%}
+ |
+
__init__ Type Parameters:": "__init__ Type Parameters:"|safe,
+ "TYPE PARAMETER": "TYPE PARAMETER",
+ "__init__ TYPE PARAMETER": "__init__ TYPE PARAMETER"|safe,
"WARNS": "WARNS",
"Warns:": "Warns:",
"YIELDS": "YIELDS",
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja
index 508e5660..f1e110a8 100644
--- a/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary.html.jinja
@@ -2,7 +2,7 @@
{% block logs scoped %}
{#- Logging block.
-
+
This block can be used to log debug messages, deprecation messages, warnings, etc.
-#}
{% endblock logs %}
@@ -12,6 +12,10 @@
{% include "summary/modules"|get_template with context %}
{% endif %}
+ {% if config.summary.type_aliases %}
+ {% include "summary/type_aliases"|get_template with context %}
+ {% endif %}
+
{% if config.summary.classes %}
{% include "summary/classes"|get_template with context %}
{% endif %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/type_aliases.html b/src/mkdocstrings_handlers/python/templates/material/_base/summary/type_aliases.html
new file mode 100644
index 00000000..bf0e6ca0
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/type_aliases.html
@@ -0,0 +1,11 @@
+{% extends "_base/summary/type_aliases.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/type_aliases/classes.html' is deprecated, extend '_base/type_aliases/classes.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/summary/type_aliases.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/summary/type_aliases.html.jinja
new file mode 100644
index 00000000..ce62269c
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/summary/type_aliases.html.jinja
@@ -0,0 +1,21 @@
+{#- Summary of type aliases. -#}
+
+{% block logs scoped %}
+ {#- Logging block.
+
+ This block can be used to log debug messages, deprecation messages, warnings, etc.
+ -#}
+{% endblock logs %}
+
+{% with section = obj.type_aliases
+ |filter_objects(
+ filters=config.filters,
+ members_list=members_list,
+ inherited_members=config.inherited_members,
+ keep_no_docstrings=config.show_if_no_docstring,
+ )
+ |order_members(config.members_order, members_list)
+ |as_type_aliases_section(check_public=not members_list)
+ %}
+ {% if section %}{% include "docstring/type_aliases"|get_template with context %}{% endif %}
+{% endwith %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html b/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html
new file mode 100644
index 00000000..18b50751
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html
@@ -0,0 +1,11 @@
+{% extends "_base/type_alias.html.jinja" %}
+
+{% block logs scoped %}
+ {{ super() }}
+ {# TODO: Switch to a warning after some time. #}
+ {{ log.info(
+ "DeprecationWarning: Extending '_base/type_alias.html' is deprecated, extend '_base/type_alias.html.jinja' instead. " ~
+ "After some time, this message will be logged as a warning, causing strict builds to fail.",
+ once=True,
+ ) }}
+{% endblock logs %}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html.jinja
new file mode 100644
index 00000000..5a21f8a6
--- /dev/null
+++ b/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html.jinja
@@ -0,0 +1,117 @@
+{#- Template for Python type aliases.
+
+This template renders a Python type alias.
+
+Context:
+ type_alias (griffe.TypeAlias): The type alias to render.
+ root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+ heading_level (int): The HTML heading level to use.
+ 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 " + type_alias.path) }}
+{% endblock logs %}
+
+
- Class
+
+
+ Class
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- Subclass
+
+
+ Subclass
+