diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index dbf3b65..6b2e888 100644 --- a/docs/usage/configuration/signatures.md +++ b/docs/usage/configuration/signatures.md @@ -331,3 +331,29 @@ function(param1, param2=None)

Function docstring.

//// /// + + +## `unwrap_annotated` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to unwrap [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated){ .external } +types to show only the type without the annotations. + +For example, unwrapping `Annotated[int, Gt(10)]` will render `int`. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + unwrap_annotated: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + unwrap_annotated: true +``` diff --git a/mkdocs.yml b/mkdocs.yml index 3154436..17b9249 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -161,6 +161,7 @@ plugins: show_symbol_type_toc: true signature_crossrefs: true summary: true + unwrap_annotated: true - git-committers: enabled: !ENV [DEPLOY, false] repository: mkdocstrings/python diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 637636b..3fc7a4f 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -109,6 +109,7 @@ class PythonHandler(BaseHandler): "annotations_path": "brief", "preload_modules": None, "allow_inspection": True, + "unwrap_annotated": False, } """ Attributes: General options: @@ -180,6 +181,7 @@ class PythonHandler(BaseHandler): signature_crossrefs (bool): Whether to render cross-references for type annotations in signatures. Default: `False`. separate_signature (bool): Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it. Default: `False`. + unwrap_annotated (bool): Whether to unwrap `Annotated` types to show only the type without the annotations. Default: `False`. """ def __init__( diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html index 6ba7896..cbc84e4 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html @@ -25,6 +25,8 @@ {%- if signature -%}{{ expression|safe }}{%- else -%}{{ expression }}{%- endif -%} {%- elif expression.classname == "ExprName" -%} {{ crossref(expression, annotations_path) }} + {%- elif config.unwrap_annotated and expression.classname == "ExprSubscript" and expression.canonical_path in ("typing.Annotated", "typing_extensions.Annotated") -%} + {{ render(expression.slice.elements[0], annotations_path) }} {%- elif expression.classname == "ExprAttribute" -%} {%- if annotations_path == "brief" -%} {{ render(expression.last, "brief") }}