Style deprecation notices in the API reference (#329)

Preparation for the client-common 0.4.1 update, so deprecation notices
already look right by the time it adds them.

Two things: a CSS rule that styles the `deprecated` admonition class
(gravestone icon, its own colour, otherwise like a warning), and the
[griffe-warnings-deprecated](https://mkdocstrings.github.io/griffe-warnings-deprecated/)
extension wired into the mkdocstrings handler so symbols decorated with
`typing_extensions.deprecated` get an admonition generated for them.

The extension's `kind` is set to `deprecated` rather than the default
`warning`, so what it emits is markup-identical to a hand-written
`Deprecated:` admonition. One rule styles both, which matters because
the decorator cannot reach module-level aliases, a single function
argument, enum members or whole modules.

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

@@ -55,6 +55,7 @@ dev-flake8 = [
 dev-formatting = ["black == 26.5.1", "isort == 8.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",