Style deprecation notices in the API reference (#336)

Author: llucax

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

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

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.

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