From 16da63e5b59950b5b9c3609a149c112218def2b5 Mon Sep 17 00:00:00 2001 From: Marco Ricci Date: Thu, 16 Jan 2025 21:29:04 +0100 Subject: [PATCH] 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()