fix: Parse Deprecated sections in Google-style docstrings

The code to parse these sections already existed, but the "Deprecated" section header was missing from the table of known section headers. Being an unknown section, Griffe then treated this as an admonition.

Griffe initially required a version indicator in Google-style Deprecated sections. This change now allows it to be missing, in which case the version is the empty string.

Issue-352: #352
PR-353: #353

Author: the-13th-letter

src/_griffe/docstrings/google.py

@@ -69,6 +69,7 @@
     "modules": DocstringSectionKind.modules,
     "warns": DocstringSectionKind.warns,
     "warnings": DocstringSectionKind.warns,
+    "deprecated": DocstringSectionKind.deprecated,
 }
 
 _BlockItem = tuple[int, list[str]]
@@ -705,8 +706,7 @@ def _read_deprecated_section(
     try:
         version, text = text.split(":", 1)
     except ValueError:
-        docstring_warning(docstring, new_offset, f"Could not parse version, text at line {offset}")
-        return None, new_offset
+        version = ""
 
     version = version.lstrip()
     description = text.lstrip()

tests/test_docstrings/test_google.py

@@ -525,6 +525,28 @@ def test_parse_yields_section(parse_google: ParserType) -> None:
     assert "'x'" in warnings[0]
 
 
+def test_parse_deprecated_section(parse_google: ParserType) -> None:
+    """Parse Deprecated section.
+
+    See [`mkdocstrings/griffe#352`](https://github.com/mkdocstrings/griffe/issues/352)
+    for context.
+
+    Parameters:
+        parse_google: Fixture parser.
+    """
+    docstring = """
+        Deprecated:
+            1.0: This function is deprecated.
+    """
+    sections, warnings = parse_google(docstring)
+    assert len(sections) == 1
+    deprecated = sections[0]
+    assert deprecated.kind is DocstringSectionKind.deprecated
+    assert deprecated.value.version == "1.0"
+    assert deprecated.value.description == "This function is deprecated."
+    assert not warnings
+
+
 def test_invalid_sections(parse_google: ParserType) -> None:
     """Warn on invalid sections.
 
@@ -1131,6 +1153,60 @@ def test_parse_returns_tuple_in_generator(parse_google: ParserType) -> None:
     assert returns[1].annotation.name == "float"
 
 
+# =============================================================================================
+# Deprecated sections
+
+
+def test_parse_deprecated_section_missing_version(parse_google: ParserType) -> None:
+    """Parse version numbers in Deprecated sections that aren't numbers.
+
+    See [`mkdocstrings/griffe#352`](https://github.com/mkdocstrings/griffe/issues/352)
+    for context.
+
+    Parameters:
+        parse_google: Fixture parser.
+    """
+    docstring = """
+        Summary.
+
+        Deprecated:
+            Since "Dapper Drake": This function is deprecated.
+    """
+    sections, warnings = parse_google(docstring)
+    assert len(sections) == 2
+    deprecated = sections[1]
+    assert deprecated.kind is DocstringSectionKind.deprecated
+    assert deprecated.value.version == 'Since "Dapper Drake"'
+    assert deprecated.value.description == "This function is deprecated."
+    assert not warnings
+
+
+def test_dont_warn_about_missing_deprecated_version(parse_google: ParserType) -> None:
+    """Don't warn about missing version info in Deprecated sections.
+
+    Also assert that we don't just swallow the section, but actually parse it.
+
+    See [`mkdocstrings/griffe#352`](https://github.com/mkdocstrings/griffe/issues/352)
+    for context.
+
+    Parameters:
+        parse_google: Fixture parser.
+    """
+    docstring = """
+        Summary.
+
+        Deprecated:
+            This function is deprecated since v0.9alpha1.
+    """
+    sections, warnings = parse_google(docstring)
+    assert len(sections) == 2
+    deprecated = sections[1]
+    assert deprecated.kind is DocstringSectionKind.deprecated
+    assert not deprecated.value.version
+    assert deprecated.value.description == "This function is deprecated since v0.9alpha1."
+    assert not warnings
+
+
 # =============================================================================================
 # Parser special features
 def test_parse_admonitions(parse_google: ParserType) -> None: