Summary.
+Type Aliases:
+ +**Name** | **Description** +------------ | ---------------- +`TypeAlias` | Some type alias. + +TypeAliasSummary.
+//// + +//// tab | Without classes +Summary.
+TypeAliasSummary.
+//// +/// + [](){#option-show_docstring_modules} ## `show_docstring_modules` @@ -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" }** + + +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.
+//// +/// + [](){#option-show_docstring_warns} ## `show_docstring_warns` diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index 0c253f1f..24bf3770 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -197,6 +197,286 @@ To customize symbols, see [Customizing symbol types](../customization.md/#symbol /// +[](){#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. + +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.
+//// +/// + [](){#option-separate_signature} ## `separate_signature` diff --git a/docs/usage/customization.md b/docs/usage/customization.md index 8239c2e9..26fe789b 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 %}
@@ -83,26 +94,31 @@ Context:
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 and config.show_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:") }}
+| {{ 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:") }}
+{{ 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() }} | +{{ 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 -%}
+ |
+
- 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
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- Subclass
+
+
+ Subclass
+
- Class
+
+
+ Class
+
- Subclass
+
+
+ Subclass
+
- 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
+
- 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
+
- NestedClass
+
+
+ NestedClass
+
- 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
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- NestedClass
+
+
+ NestedClass
+
- Subclass
+
+
+ Subclass
+
- NestedClass
+
+
+ NestedClass
+
- Class
+
+
+ Class
+
- Class
+
+
+ Class
+
- Class
+
+
+ Class
+
- Class
+
+
+ Class
+