From c5f7ed2d66d4cc04afb026ff56eb436c3090ef4e Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 12:53:13 +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 3513b8ae0dd7a9f3c98da8e36f0a1deba90d20b0 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 12:53:13 +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 97524e82..694788df 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 8f946b8c..4e4132c9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,6 +72,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 9a7c0f4fa1b1aa3a12b315024b609c6b01dc1129 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 16:53:04 +0000 Subject: [PATCH 3/3] docs: Announce the deprecated argument and enum member The `key` argument of `DispatchApiClient.__init__` and the `SOLAR` member of `InverterType` were both deprecated in v0.11.2, but said so only in passing prose, so neither showed a deprecation notice in the API reference. Give both a `Deprecated:` admonition, right after the summary line and without a custom title, so they render like the ones the griffe extension generates. The decorator reaches neither an argument nor an enum member, so a hand-written admonition is the only channel for them. The `--api-key` option is deprecated too, but `__main__` is not part of the API reference, so an admonition there would render nowhere. That deprecation stays where it is visible, in the `--help` text and the notice printed at runtime. Signed-off-by: Leandro Lucarella --- src/frequenz/client/dispatch/_client.py | 4 ++++ src/frequenz/client/dispatch/types.py | 7 ++++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/src/frequenz/client/dispatch/_client.py b/src/frequenz/client/dispatch/_client.py index 9381c4e9..a3150fdc 100644 --- a/src/frequenz/client/dispatch/_client.py +++ b/src/frequenz/client/dispatch/_client.py @@ -69,6 +69,10 @@ def __init__( ) -> None: """Initialize the client. + Deprecated: + The `key` argument is deprecated since v0.11.2. Pass `auth_key` + instead. + Args: server_url: The URL of the server to connect to. auth_key: API key to use for authentication. diff --git a/src/frequenz/client/dispatch/types.py b/src/frequenz/client/dispatch/types.py index be954371..709cb097 100644 --- a/src/frequenz/client/dispatch/types.py +++ b/src/frequenz/client/dispatch/types.py @@ -106,7 +106,12 @@ class InverterType(Enum): """Solar inverter.""" SOLAR = PBInverterType.INVERTER_TYPE_PV - """Deprecated, Solar inverter.""" + """Solar inverter (deprecated). + + Deprecated: + This member is deprecated since v0.11.2. Use + [`PV`][frequenz.client.dispatch.types.InverterType.PV] instead. + """ HYBRID = PBInverterType.INVERTER_TYPE_HYBRID """Hybrid inverter."""