Skip to content

Commit

Permalink
fix: Parse Deprecated sections without version info in Google-style d…
Browse files Browse the repository at this point in the history
…ocstrings

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]: mkdocstrings/python#166 (comment) '"the source form of the docstring should be readable"'
[2]: google/styleguide#117 (comment)  '"Docstrings are meant for human consumption, please keep them readable for us humans. :)"'

Issue-352: #352
  • Loading branch information
the-13th-letter committed Jan 16, 2025
1 parent 259a8fe commit 16da63e
Showing 1 changed file with 4 additions and 1 deletion.
5 changes: 4 additions & 1 deletion src/_griffe/docstrings/google.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down

0 comments on commit 16da63e

Please sign in to comment.