refactor: Remove Google parser support for Deprecated sections (previ…

…ously never used)

Also stop mentioning this section in docs. The goal is to deprecate it once the Numpy parser supports custom titles for admonitions.

docs/reference/docstrings.md

@@ -303,20 +303,6 @@ Modules:
 """
 ```
 
-#### Deprecated {#google-section-deprecated}
-
-Deprecated sections allow to document a deprecation that happened at a particular version. They can be used in every docstring.
-
-```python
-"""My module.
-
-Deprecated:
-    1.2: The `foo` attribute is deprecated.
-"""
-
-foo: int = 0
-```
-
 #### Examples {#google-section-examples}
 
 Examples sections allow to add examples of Python code without the use of markup code blocks. They are a mix of prose and interactive console snippets. They can be used in every docstring.
@@ -1042,22 +1028,6 @@ bar
 """
 ```
 
-#### Deprecated {#numpydoc-section-deprecated}
-
-Deprecated sections allow to document a deprecation that happened at a particular version. They can be used in every docstring.
-
-```python
-"""My module.
-
-Deprecated
-----------
-    1.2
-        The `foo` attribute is deprecated.
-"""
-
-foo: int = 0
-```
-
 #### Examples {#numpydoc-section-examples}
 
 Examples sections allow to add examples of Python code without the use of markup code blocks. They are a mix of prose and interactive console snippets. They can be used in every docstring.
@@ -1444,7 +1414,6 @@ For non-Insiders versions, `default` is returned if specified, else the first pa
 
     The sections are easier to deal in that order:
 
-    - Deprecated (single item, version and text)
     - Raises, Warns (multiple items, no names, single type each)
     - Attributes, Other Parameters, Parameters (multiple items, one name and one optional type each)
     - Returns (multiple items, optional name and/or type each, annotation to split when multiple names)
@@ -1463,7 +1432,6 @@ Functions        | ✅     | ✅    | ❌
 Methods          | ✅     | ✅    | ❌
 Classes          | ✅     | ✅    | ❌
 Modules          | ✅     | ✅    | ❌
-Deprecated       | ✅     | ✅[^1]| [❌][issue-section-sphinx-deprecated]
 Examples         | ✅     | ✅    | [❌][issue-section-sphinx-examples]
 Parameters       | ✅     | ✅    | ✅
 Other Parameters | ✅     | ✅    | [❌][issue-section-sphinx-other-parameters]
@@ -1473,8 +1441,6 @@ Yields           | ✅     | ✅    | [❌][issue-section-sphinx-yields]
 Receives         | ✅     | ✅    | [❌][issue-section-sphinx-receives]
 Returns          | ✅     | ✅    | ✅
 
-[^1]: Support for a regular section instead of the RST directive specified in the [Numpydoc styleguide](https://numpydoc.readthedocs.io/en/latest/format.html#deprecation-warning).
-
 ### Getting annotations/defaults from parent
 
 Section          | Google | Numpy | Sphinx
@@ -1484,7 +1450,6 @@ Functions        | /      | /     | /
 Methods          | /      | /     | /
 Classes          | /      | /     | /
 Modules          | /      | /     | /
-Deprecated       | /      | /     | /
 Examples         | /      | /     | /
 Parameters       | ✅     | ✅    | ✅
 Other Parameters | ✅     | ✅    | [❌][issue-parent-sphinx-other-parameters]
@@ -1503,7 +1468,6 @@ Functions        | [❌][issue-xref-google-func-cls] | [❌][issue-xref-numpy-fu
 Methods          | [❌][issue-xref-google-func-cls] | [❌][issue-xref-numpy-func-cls] | /
 Classes          | [❌][issue-xref-google-func-cls] | [❌][issue-xref-numpy-func-cls] | /
 Modules          | /      | /     | /
-Deprecated       | /      | /     | /
 Examples         | /      | /     | /
 Parameters       | ✅     | ✅    | [❌][issue-xref-sphinx-parameters]
 Other Parameters | ✅     | ✅    | [❌][issue-xref-sphinx-other-parameters]
@@ -1519,7 +1483,6 @@ Returns          | ✅     | ✅    | [❌][issue-xref-sphinx-returns]
 [issue-parent-sphinx-other-parameters]: https://github.com/mkdocstrings/griffe/issues/34
 [issue-parent-sphinx-receives]: https://github.com/mkdocstrings/griffe/issues/35
 [issue-parent-sphinx-yields]: https://github.com/mkdocstrings/griffe/issues/36
-[issue-section-sphinx-deprecated]: https://github.com/mkdocstrings/griffe/issues/6
 [issue-section-sphinx-examples]: https://github.com/mkdocstrings/griffe/issues/7
 [issue-section-sphinx-other-parameters]: https://github.com/mkdocstrings/griffe/issues/27
 [issue-section-sphinx-receives]: https://github.com/mkdocstrings/griffe/issues/8

src/_griffe/docstrings/google.py

@@ -19,7 +19,6 @@
     DocstringSectionAdmonition,
     DocstringSectionAttributes,
     DocstringSectionClasses,
-    DocstringSectionDeprecated,
     DocstringSectionExamples,
     DocstringSectionFunctions,
     DocstringSectionModules,
@@ -693,30 +692,6 @@ def _read_examples_section(
     return DocstringSectionExamples(sub_sections), new_offset
 
 
-def _read_deprecated_section(
-    docstring: Docstring,
-    *,
-    offset: int,
-    **options: Any,
-) -> tuple[DocstringSectionDeprecated | None, int]:
-    text, new_offset = _read_block(docstring, offset=offset, **options)
-
-    # check the presence of a name and description, separated by a semi-colon
-    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.lstrip()
-    description = text.lstrip()
-
-    return (
-        DocstringSectionDeprecated(version=version, text=description),
-        new_offset,
-    )
-
-
 def _is_empty_line(line: str) -> bool:
     return not line.strip()
 
@@ -734,7 +709,6 @@ def _is_empty_line(line: str) -> bool:
     DocstringSectionKind.returns: _read_returns_section,
     DocstringSectionKind.yields: _read_yields_section,
     DocstringSectionKind.receives: _read_receives_section,
-    DocstringSectionKind.deprecated: _read_deprecated_section,
 }
 
 _sentinel = object()