feat: Add option to unwrap Annotated types

pawamoy · pawamoy · commit 53db04b6256d · 2023-09-14T15:28:58.000+02:00
diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md
@@ -331,3 +331,29 @@ function(param1, param2=None)
 <p>Function docstring.</p>
 ////
 ///
+
+
+## `unwrap_annotated`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+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
@@ -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
@@ -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
@@ -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") }}
