From d55b05db4d8f36ff8e4e92001f18784fe26676f9 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 12:52:18 +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 572abff1..851214f2 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 6d8401af99ed34e491590ef20c1fc6c6fbf0a892 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 12:52:19 +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 1cb74e30..f22e9d49 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 1b42cbf8..97db6618 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -64,6 +64,7 @@ dev-flake8 = [ dev-formatting = ["black == 26.5.1", "isort == 9.0.1"] dev-mkdocs = [ "black == 26.5.1", + "griffe-warnings-deprecated == 1.1.1", "Markdown==3.10.3", "mike == 2.2.0", "mkdocs-gen-files == 0.6.1", From 22ce99ea62b0d848b27f33796cb307a2349281b1 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 16:53:04 +0000 Subject: [PATCH 3/3] docs: Drop the custom title from the deprecation admonitions All 35 deprecation notices were written as `Deprecated: Deprecated in v0.18.0`. A custom title replaces the word "Deprecated" in the rendered output, so every one of them came out labelled "Deprecated in v0.18.0", losing the very word the styling added in this branch keys on, and reading differently from the admonitions the griffe extension generates. Drop the title and state the version in the admonition text instead, which is what the deprecations guide asks for. Signed-off-by: Leandro Lucarella --- .../client/microgrid/component/_category.py | 6 +- .../microgrid/component/_state_sample.py | 3 +- .../client/microgrid/metrics/_metric.py | 96 ++++++++++++------- 3 files changed, 70 insertions(+), 35 deletions(-) diff --git a/src/frequenz/client/microgrid/component/_category.py b/src/frequenz/client/microgrid/component/_category.py index ef9148d0..540d78c8 100644 --- a/src/frequenz/client/microgrid/component/_category.py +++ b/src/frequenz/client/microgrid/component/_category.py @@ -27,7 +27,8 @@ class ComponentCategory(enum.Enum): ) """The point where the local microgrid is connected to the grid (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`GRID_CONNECTION_POINT`][frequenz.client.microgrid.component.ComponentCategory.GRID_CONNECTION_POINT] instead. @@ -96,7 +97,8 @@ class ComponentCategory(enum.Enum): ) """A voltage transformer (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`POWER_TRANSFORMER`][frequenz.client.microgrid.component.ComponentCategory.POWER_TRANSFORMER] instead. diff --git a/src/frequenz/client/microgrid/component/_state_sample.py b/src/frequenz/client/microgrid/component/_state_sample.py index 5829f8ac..93318aba 100644 --- a/src/frequenz/client/microgrid/component/_state_sample.py +++ b/src/frequenz/client/microgrid/component/_state_sample.py @@ -188,7 +188,8 @@ class ComponentErrorCode(enum.Enum): ) """System shutdown due to undervoltage involving this component. - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`UNDERVOLTAGE`][frequenz.client.microgrid.component.ComponentErrorCode.UNDERVOLTAGE] instead. diff --git a/src/frequenz/client/microgrid/metrics/_metric.py b/src/frequenz/client/microgrid/metrics/_metric.py index e99daf0c..cae2fc5a 100644 --- a/src/frequenz/client/microgrid/metrics/_metric.py +++ b/src/frequenz/client/microgrid/metrics/_metric.py @@ -81,7 +81,8 @@ class Metric(enum.Enum): ) """The alternating current apparent power (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_APPARENT`][frequenz.client.microgrid.metrics.Metric.AC_POWER_APPARENT] instead. """ @@ -95,7 +96,8 @@ class Metric(enum.Enum): ) """The alternating current apparent power in phase 1 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_APPARENT_PHASE_1`][frequenz.client.microgrid.metrics.Metric.AC_POWER_APPARENT_PHASE_1] instead. """ @@ -109,7 +111,8 @@ class Metric(enum.Enum): ) """The alternating current apparent power in phase 2 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_APPARENT_PHASE_2`][frequenz.client.microgrid.metrics.Metric.AC_POWER_APPARENT_PHASE_2] instead. """ @@ -123,7 +126,8 @@ class Metric(enum.Enum): ) """The alternating current apparent power in phase 3 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_APPARENT_PHASE_3`][frequenz.client.microgrid.metrics.Metric.AC_POWER_APPARENT_PHASE_3] instead. """ @@ -137,7 +141,8 @@ class Metric(enum.Enum): ) """The alternating current active power (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_ACTIVE`][frequenz.client.microgrid.metrics.Metric.AC_POWER_ACTIVE] instead. """ @@ -151,7 +156,8 @@ class Metric(enum.Enum): ) """The alternating current active power in phase 1 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_ACTIVE_PHASE_1`][frequenz.client.microgrid.metrics.Metric.AC_POWER_ACTIVE_PHASE_1] instead. """ @@ -165,7 +171,8 @@ class Metric(enum.Enum): ) """The alternating current active power in phase 2 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_ACTIVE_PHASE_2`][frequenz.client.microgrid.metrics.Metric.AC_POWER_ACTIVE_PHASE_2] instead. """ @@ -179,7 +186,8 @@ class Metric(enum.Enum): ) """The alternating current active power in phase 3 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_ACTIVE_PHASE_3`][frequenz.client.microgrid.metrics.Metric.AC_POWER_ACTIVE_PHASE_3] instead. """ @@ -193,7 +201,8 @@ class Metric(enum.Enum): ) """The alternating current reactive power (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_REACTIVE`][frequenz.client.microgrid.metrics.Metric.AC_POWER_REACTIVE] instead. """ @@ -207,7 +216,8 @@ class Metric(enum.Enum): ) """The alternating current reactive power in phase 1 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_REACTIVE_PHASE_1`][frequenz.client.microgrid.metrics.Metric.AC_POWER_REACTIVE_PHASE_1] instead. """ @@ -221,7 +231,8 @@ class Metric(enum.Enum): ) """The alternating current reactive power in phase 2 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_REACTIVE_PHASE_2`][frequenz.client.microgrid.metrics.Metric.AC_POWER_REACTIVE_PHASE_2] instead. """ @@ -235,7 +246,8 @@ class Metric(enum.Enum): ) """The alternating current reactive power in phase 3 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_POWER_REACTIVE_PHASE_3`][frequenz.client.microgrid.metrics.Metric.AC_POWER_REACTIVE_PHASE_3] instead. """ @@ -261,7 +273,8 @@ class Metric(enum.Enum): ) """The alternating current apparent energy (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_APPARENT`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_APPARENT] instead. """ @@ -275,7 +288,8 @@ class Metric(enum.Enum): ) """The alternating current apparent energy in phase 1 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_APPARENT_PHASE_1`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_APPARENT_PHASE_1] instead. """ @@ -289,7 +303,8 @@ class Metric(enum.Enum): ) """The alternating current apparent energy in phase 2 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_APPARENT_PHASE_2`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_APPARENT_PHASE_2] instead. """ @@ -303,7 +318,8 @@ class Metric(enum.Enum): ) """The alternating current apparent energy in phase 3 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_APPARENT_PHASE_3`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_APPARENT_PHASE_3] instead. """ @@ -317,7 +333,8 @@ class Metric(enum.Enum): ) """The alternating current active energy (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE] instead. """ @@ -331,7 +348,8 @@ class Metric(enum.Enum): ) """The alternating current active energy in phase 1 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_PHASE_1`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_PHASE_1] instead. """ @@ -345,7 +363,8 @@ class Metric(enum.Enum): ) """The alternating current active energy in phase 2 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_PHASE_2`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_PHASE_2] instead. """ @@ -359,7 +378,8 @@ class Metric(enum.Enum): ) """The alternating current active energy in phase 3 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_PHASE_3`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_PHASE_3] instead. """ @@ -373,7 +393,8 @@ class Metric(enum.Enum): ) """The alternating current active energy consumed (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_CONSUMED`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_CONSUMED] instead. """ @@ -389,7 +410,8 @@ class Metric(enum.Enum): ) """The alternating current active energy consumed in phase 1 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_CONSUMED_PHASE_1`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_CONSUMED_PHASE_1] instead. """ @@ -405,7 +427,8 @@ class Metric(enum.Enum): ) """The alternating current active energy consumed in phase 2 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_CONSUMED_PHASE_2`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_CONSUMED_PHASE_2] instead. """ @@ -421,7 +444,8 @@ class Metric(enum.Enum): ) """The alternating current active energy consumed in phase 3 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_CONSUMED_PHASE_3`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_CONSUMED_PHASE_3] instead. """ @@ -435,7 +459,8 @@ class Metric(enum.Enum): ) """The alternating current active energy delivered (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_DELIVERED`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_DELIVERED] instead. """ @@ -451,7 +476,8 @@ class Metric(enum.Enum): ) """The alternating current active energy delivered in phase 1 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_DELIVERED_PHASE_1`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_DELIVERED_PHASE_1] instead. """ @@ -467,7 +493,8 @@ class Metric(enum.Enum): ) """The alternating current active energy delivered in phase 2 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_DELIVERED_PHASE_2`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_DELIVERED_PHASE_2] instead. """ @@ -483,7 +510,8 @@ class Metric(enum.Enum): ) """The alternating current active energy delivered in phase 3 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_ACTIVE_DELIVERED_PHASE_3`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_ACTIVE_DELIVERED_PHASE_3] instead. """ @@ -497,7 +525,8 @@ class Metric(enum.Enum): ) """The alternating current reactive energy (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_REACTIVE`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_REACTIVE] instead. """ @@ -511,7 +540,8 @@ class Metric(enum.Enum): ) """The alternating current reactive energy in phase 1 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_REACTIVE_PHASE_1`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_REACTIVE_PHASE_1] instead. """ @@ -525,7 +555,8 @@ class Metric(enum.Enum): ) """The alternating current reactive energy in phase 2 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_REACTIVE_PHASE_2`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_REACTIVE_PHASE_2] instead. """ @@ -539,7 +570,8 @@ class Metric(enum.Enum): ) """The alternating current reactive energy in phase 3 (deprecated). - Deprecated: Deprecated in v0.18.0 + Deprecated: + This member is deprecated since v0.18.0. Use [`AC_ENERGY_REACTIVE_PHASE_3`][frequenz.client.microgrid.metrics.Metric.AC_ENERGY_REACTIVE_PHASE_3] instead. """