From 3453e280ba749a0cf4fa76658ef979feef73b310 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 12:36:04 +0000 Subject: [PATCH 1/3] docs: Add styling for "Deprecated" admonitions Style the `deprecated` admonition class like a warning, but with the `material/grave-stone` icon and its own colour, so deprecation notices read as deprecation notices and not as generic warnings. That class is what a hand-written `Deprecated:` admonition in a docstring produces, and also what the griffe extension added next will emit, so a single rule covers both sources. Signed-off-by: Leandro Lucarella --- docs/_css/mkdocstrings.css | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/_css/mkdocstrings.css b/docs/_css/mkdocstrings.css index 572abff..851214f 100644 --- a/docs/_css/mkdocstrings.css +++ b/docs/_css/mkdocstrings.css @@ -42,3 +42,25 @@ a.autorefs-external::after { a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); } + +/* A "Deprecated" admonition, styled like a warning but with its own icon. */ +:root { + --md-admonition-icon--deprecated: url('data:image/svg+xml;charset=utf-8,'); +} + +.md-typeset .admonition.deprecated, +.md-typeset details.deprecated { + border-color: #cc9900; +} + +.md-typeset .deprecated > .admonition-title, +.md-typeset .deprecated > summary { + background-color: #cc99001a; +} + +.md-typeset .deprecated > .admonition-title::before, +.md-typeset .deprecated > summary::before { + background-color: #cc9900; + -webkit-mask-image: var(--md-admonition-icon--deprecated); + mask-image: var(--md-admonition-icon--deprecated); +} From 62c33381ca00ab4d98c052f59beecaf9ec90d16d Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 12:36:14 +0000 Subject: [PATCH 2/3] docs: Generate "Deprecated" admonitions automatically Wire the `griffe-warnings-deprecated` extension into the mkdocstrings handler options, so every symbol decorated with `typing_extensions.deprecated` gets a "Deprecated" admonition in the API reference with no docstring edit at all. The extension's `kind` is set to `deprecated` rather than the default `warning`, so it emits `class="deprecated"`, which is exactly what a hand-written `Deprecated:` admonition produces. The CSS rule added in the previous commit then styles both, and the two are visually indistinguishable. That matters because the decorator cannot reach everything: module-level aliases, a single function argument, enum members and whole modules still need the admonition written by hand. Signed-off-by: Leandro Lucarella --- mkdocs.yml | 4 ++++ pyproject.toml | 1 + 2 files changed, 5 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index d839d3d..d69c365 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -101,6 +101,10 @@ plugins: python: paths: ["src"] options: + extensions: + - griffe_warnings_deprecated: + kind: deprecated + title: Deprecated docstring_section_style: spacy inherited_members: true merge_init_into_class: false diff --git a/pyproject.toml b/pyproject.toml index 672e977..2ea7884 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,6 +57,7 @@ dev-formatting = ["black == 26.5.1", "isort == 9.0.1"] dev-mkdocs = [ "Markdown == 3.10.3", "black == 26.5.1", + "griffe-warnings-deprecated == 1.1.1", "mike == 2.2.0", "mkdocs-gen-files == 0.6.1", "mkdocs-literate-nav == 0.6.3", From cafa552ff50e13992314ae5b9ee999bb28a2b720 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 16:53:03 +0000 Subject: [PATCH 3/3] docs: Convert the deprecation notice to a `Deprecated:` admonition `LessThanComparableOrNoneT` announced its deprecation through a `Warning: Deprecated` admonition, which renders as an ordinary warning and so reads like any other caveat. Write it as a `Deprecated:` admonition instead, so it picks up the deprecation styling added in this branch, and state the version that deprecated it in the text, as the deprecations guide requires. The decorator cannot reach a module-level type variable, so a hand-written admonition is the only channel there is. Signed-off-by: Leandro Lucarella --- src/frequenz/core/math.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/frequenz/core/math.py b/src/frequenz/core/math.py index 2d1bb88..151f306 100644 --- a/src/frequenz/core/math.py +++ b/src/frequenz/core/math.py @@ -45,9 +45,9 @@ def __lt__(self, other: Self, /) -> bool: ) """Type variable for a value that is [`LessThanComparable`][..LessThanComparable] or `None`. -Warning: Deprecated - This type variable is deprecated and it will be removed in a future version. Use - [`LessThanComparableT`][..LessThanComparableT] instead. +Deprecated: + This type variable is deprecated since v1.4.0 and it will be removed in a + future version. Use [`LessThanComparableT`][..LessThanComparableT] instead. """