From b557ff31cd7394b20487aa204b16a5c3710f4f4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 17 Feb 2025 13:37:10 +0100 Subject: [PATCH 1/5] docs: Fix canonical path in Griffe extension for our custom config fields --- scripts/griffe_extensions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/griffe_extensions.py b/scripts/griffe_extensions.py index 4ff0c8cc..7d283054 100644 --- a/scripts/griffe_extensions.py +++ b/scripts/griffe_extensions.py @@ -28,7 +28,7 @@ def on_attribute_instance( except AttributeError: return - if field.canonical_path == "mkdocstrings_handler.python.config.Field": + if field.canonical_path == "mkdocstrings_handlers.python.config.Field": description = next( attr.value for attr in field.arguments From d809f1a9e6a6f4eaf6fe4a18c2ec0e69e5716a12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 17 Feb 2025 15:36:12 +0100 Subject: [PATCH 2/5] fix: Unwrap `Annotated` regardless of `signature_crossrefs` Issue-249: https://github.com/mkdocstrings/python/issues/249 --- .../python/templates/material/_base/signature.html.jinja | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja index eb8cf552..ce5c3f04 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/signature.html.jinja @@ -47,7 +47,7 @@ Context: {#- Prepare type annotation. -#} {%- if config.show_signature_annotations and parameter.annotation is not none -%} {%- set ns.equal = " = " -%} - {%- if config.separate_signature and config.signature_crossrefs -%} + {%- if config.separate_signature -%} {%- with expression = parameter.annotation -%} {%- set ns.annotation -%}: {% include "expression"|get_template with context %}{%- endset -%} {%- endwith -%} From 20cae2cb79224caf9de335f6766e1fc4bb02d9d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 17 Feb 2025 15:36:51 +0100 Subject: [PATCH 3/5] chore: Prepare release 1.15.1 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ec57bf03..6e8f8fe8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ 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). +## [1.15.1](https://github.com/mkdocstrings/python/releases/tag/1.15.1) - 2025-02-17 + +[Compare with 1.15.0](https://github.com/mkdocstrings/python/compare/1.15.0...1.15.1) + +### Bug Fixes + +- Unwrap `Annotated` regardless of `signature_crossrefs` ([d809f1a](https://github.com/mkdocstrings/python/commit/d809f1a9e6a6f4eaf6fe4a18c2ec0e69e5716a12) by Timothée Mazzucotelli). [Issue-249](https://github.com/mkdocstrings/python/issues/249) + ## [1.15.0](https://github.com/mkdocstrings/python/releases/tag/1.15.0) - 2025-02-11 [Compare with 1.14.6](https://github.com/mkdocstrings/python/compare/1.14.6...1.15.0) From 4a5ee10c65de28b7921a56ef2c222d2f3417edaa Mon Sep 17 00:00:00 2001 From: Pete Stenger Date: Mon, 17 Feb 2025 08:43:04 -0600 Subject: [PATCH 4/5] feat: Add option to show/hide overloads PR-250: https://github.com/mkdocstrings/python/pull/250 --- docs/usage/configuration/signatures.md | 49 +++++++++++++++++++ src/mkdocstrings_handlers/python/config.py | 8 +++ .../templates/material/_base/class.html.jinja | 2 +- .../material/_base/function.html.jinja | 2 +- 4 files changed, 59 insertions(+), 2 deletions(-) diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index c97cb5a6..98c865e5 100644 --- a/docs/usage/configuration/signatures.md +++ b/docs/usage/configuration/signatures.md @@ -433,6 +433,55 @@ function(param1, param2=None) //// /// +[](){#option-show_overloads} +## `show_overloads` + +Whether to render function / method overloads. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_overloads: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + show_overloads: false +``` + +/// admonition | Preview + type: preview +//// tab | With overloads +

function

+ + +```python +@overload +function(param1: int): ... + +@overload +function(param1: str): ... + +function(param1: str | int) +``` +Function docstring. + +//// +//// tab | Without overloads +

function

+ +```python +function(param1: str | int) +``` +Function docstring. + +//// +/// + [](){#option-signature_crossrefs} ## `signature_crossrefs` diff --git a/src/mkdocstrings_handlers/python/config.py b/src/mkdocstrings_handlers/python/config.py index 3bab3920..6607d01c 100644 --- a/src/mkdocstrings_handlers/python/config.py +++ b/src/mkdocstrings_handlers/python/config.py @@ -568,6 +568,14 @@ class PythonInputOptions: ), ] = False + show_overloads: Annotated[ + bool, + Field( + group="signatures", + description="Show the overloads of a function or method.", + ), + ] = True + separate_signature: Annotated[ bool, Field( diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index aefa98d1..e8f89fa3 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -82,7 +82,7 @@ Context: {% if config.merge_init_into_class %} {% if "__init__" in all_members %} {% with function = all_members["__init__"] %} - {% if function.overloads %} + {% if function.overloads and config.show_overloads %}
{% for overload in function.overloads %} {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja index 5e803ffb..b475cf1b 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja @@ -80,7 +80,7 @@ Context: This block renders the signature for the function, as well as its overloaded signatures if any. -#} - {% if function.overloads %} + {% if function.overloads and config.show_overloads %}
{% for overload in function.overloads %} {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %} From e3a303c83fbf765c6f380b3628ddb14841da3aa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 17 Feb 2025 15:45:41 +0100 Subject: [PATCH 5/5] chore: Prepare release 1.16.0 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e8f8fe8..05e4e3ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ 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). +## [1.16.0](https://github.com/mkdocstrings/python/releases/tag/1.16.0) - 2025-02-17 + +[Compare with 1.15.1](https://github.com/mkdocstrings/python/compare/1.15.1...1.16.0) + +### Features + +- Add option to show/hide overloads ([4a5ee10](https://github.com/mkdocstrings/python/commit/4a5ee10c65de28b7921a56ef2c222d2f3417edaa) by Pete Stenger). [PR-250](https://github.com/mkdocstrings/python/pull/250) + ## [1.15.1](https://github.com/mkdocstrings/python/releases/tag/1.15.1) - 2025-02-17 [Compare with 1.15.0](https://github.com/mkdocstrings/python/compare/1.15.0...1.15.1)