Style deprecation notices in the API reference

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,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 2h4c3.31 0 5 2.69 5 6v10.66C16.88 17.63 15.07 17 12 17s-4.88.63-7 1.66V8c0-3.31 1.69-6 5-6M8 8v1.5h8V8zm1 4v1.5h6V12zM3 22v-.69c2.66-1.69 10.23-5.47 18-.06V22z"/></svg>');
+}
+
+.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);
+}

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

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",

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.

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.

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.
     """