From 3cf96c5e169b508eeb731d695d256f7febddb89c Mon Sep 17 00:00:00 2001 From: Marco Ricci Date: Thu, 16 Jan 2025 21:29:04 +0100 Subject: [PATCH 1/5] tests: Add tests for Google-style Deprecated sections These tests currently fail, because the Deprecated sections are parsed as admonitions. Issue-352: https://github.com/mkdocstrings/griffe/issues/352 --- tests/test_docstrings/test_google.py | 77 ++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/tests/test_docstrings/test_google.py b/tests/test_docstrings/test_google.py index 15037b22..536fd7f6 100644 --- a/tests/test_docstrings/test_google.py +++ b/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: From 259a8fe0e6b28daf22a4b2697950f6006d5d0d41 Mon Sep 17 00:00:00 2001 From: Marco Ricci Date: Thu, 16 Jan 2025 21:29:04 +0100 Subject: [PATCH 2/5] 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. Issue-352: https://github.com/mkdocstrings/griffe/issues/352 --- src/_griffe/docstrings/google.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/_griffe/docstrings/google.py b/src/_griffe/docstrings/google.py index 7b3d408a..dc960bad 100644 --- a/src/_griffe/docstrings/google.py +++ b/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]] From 16da63e5b59950b5b9c3609a149c112218def2b5 Mon Sep 17 00:00:00 2001 From: Marco Ricci Date: Thu, 16 Jan 2025 21:29:04 +0100 Subject: [PATCH 3/5] fix: Parse Deprecated sections without version info in Google-style docstrings Griffe requires a version indicator in Google-style Deprecated sections. If no such indicator is found, then the user is warned, and *then* the section **is silently dropped**. [As a proponent of readable docstrings][1], [and apparently in spirit with the Google style guide][2], I consider it unacceptable to drop information from a docstring just because it is not properly formatted as data. In this patch, I propose parsing the section without an associated version number instead, and using the section's text as its... well, text. [1]: https://github.com/mkdocstrings/python/issues/166#issue-2341762468 '"the source form of the docstring should be readable"' [2]: https://github.com/google/styleguide/issues/117#issuecomment-203046319 '"Docstrings are meant for human consumption, please keep them readable for us humans. :)"' Issue-352: https://github.com/mkdocstrings/griffe/issues/352 --- src/_griffe/docstrings/google.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/_griffe/docstrings/google.py b/src/_griffe/docstrings/google.py index dc960bad..f40440f0 100644 --- a/src/_griffe/docstrings/google.py +++ b/src/_griffe/docstrings/google.py @@ -709,7 +709,10 @@ def _read_deprecated_section( 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 + return ( + DocstringSectionDeprecated(version="", text=text), + new_offset, + ) version = version.lstrip() description = text.lstrip() From 6d758e299c5c3571d0db60e43a731feeb26bece7 Mon Sep 17 00:00:00 2001 From: Marco Ricci Date: Fri, 17 Jan 2025 11:08:37 +0100 Subject: [PATCH 4/5] style: Update src/_griffe/docstrings/google.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per @pawamoy's suggestion. PR-353: https://github.com/mkdocstrings/griffe/pull/353 Co-authored-by: Timothée Mazzucotelli --- src/_griffe/docstrings/google.py | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/src/_griffe/docstrings/google.py b/src/_griffe/docstrings/google.py index f40440f0..f6b4e790 100644 --- a/src/_griffe/docstrings/google.py +++ b/src/_griffe/docstrings/google.py @@ -709,10 +709,7 @@ def _read_deprecated_section( version, text = text.split(":", 1) except ValueError: docstring_warning(docstring, new_offset, f"Could not parse version, text at line {offset}") - return ( - DocstringSectionDeprecated(version="", text=text), - new_offset, - ) + return DocstringSectionDeprecated(version="", text=text), new_offset version = version.lstrip() description = text.lstrip() From 60a777bf4ddd73d7f276375883ab0c56297b48c1 Mon Sep 17 00:00:00 2001 From: Marco Ricci Date: Fri, 17 Jan 2025 11:08:37 +0100 Subject: [PATCH 5/5] fix: Remove warning about missing version info in Deprecated section --- src/_griffe/docstrings/google.py | 3 +-- tests/test_docstrings/test_google.py | 7 +++---- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/src/_griffe/docstrings/google.py b/src/_griffe/docstrings/google.py index f6b4e790..8dbe9ffb 100644 --- a/src/_griffe/docstrings/google.py +++ b/src/_griffe/docstrings/google.py @@ -708,8 +708,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 DocstringSectionDeprecated(version="", text=text), new_offset + version = "" version = version.lstrip() description = text.lstrip() diff --git a/tests/test_docstrings/test_google.py b/tests/test_docstrings/test_google.py index 536fd7f6..083acf65 100644 --- a/tests/test_docstrings/test_google.py +++ b/tests/test_docstrings/test_google.py @@ -1181,8 +1181,8 @@ def test_parse_deprecated_section_missing_version(parse_google: ParserType) -> N assert not warnings -def test_warn_about_missing_deprecated_version(parse_google: ParserType) -> None: - """Warn about missing version info in Deprecated sections. +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. @@ -1204,8 +1204,7 @@ def test_warn_about_missing_deprecated_version(parse_google: ParserType) -> None 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] + assert not warnings # =============================================================================================