tests: Add tests for Google-style Deprecated sections

These tests currently fail, because the Deprecated sections are parsed
as admonitions.

Issue-352: #352

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,61 @@ 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_warn_about_missing_deprecated_version(parse_google: ParserType) -> None:
+    """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 len(warnings) == 1
+    assert "Could not parse version, text at line" in warnings[0]
+
+
 # =============================================================================================
 # Parser special features
 def test_parse_admonitions(parse_google: ParserType) -> None: