From a38ca9dc288b519fdcab0c2fb10e06ccc47b531d Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 12:53:48 +0000 Subject: [PATCH 1/2] 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 572abff..851214f 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 d82a93a200ce5a79bbcc39d0cf3e94a1439a48ec Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Mon, 21 Sep 2026 12:53:49 +0000 Subject: [PATCH 2/2] 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 d37421f..15bda8a 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 51cabc1..afdfbde 100644 --- a/pyproject.toml +++ b/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",