From 425aeceb9935be446979b669c9d557db84a36873 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sat, 18 Jan 2025 14:34:45 +0100 Subject: [PATCH] refactor: Remove Google parser support for Deprecated sections (previously 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 | 37 -------------------------------- src/_griffe/docstrings/google.py | 26 ---------------------- 2 files changed, 63 deletions(-) diff --git a/docs/reference/docstrings.md b/docs/reference/docstrings.md index 84693291..b27f1351 100644 --- a/docs/reference/docstrings.md +++ b/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 diff --git a/src/_griffe/docstrings/google.py b/src/_griffe/docstrings/google.py index f99c0a4e..3546d884 100644 --- a/src/_griffe/docstrings/google.py +++ b/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()