bug: two issues with parsing Google-style Deprecated sections

[the-13th-letter]

Description of the bug (1 of 2)

1. Griffe claims to specifically support "Deprecated" sections in Google-style docstrings, but actually parses them as general admonitions. (See the "To Reproduce" section below.) The parsing code is there, but it isn't being triggered, because "deprecated" is not recognized as a section name: it is missing from the table of known section names.

   griffe/src/_griffe/docstrings/google.py

   Lines 48 to 72 in a2f320f

   	_section_kind = {
   	"args": DocstringSectionKind.parameters,
   	"arguments": DocstringSectionKind.parameters,
   	"params": DocstringSectionKind.parameters,
   	"parameters": DocstringSectionKind.parameters,
   	"keyword args": DocstringSectionKind.other_parameters,
   	"keyword arguments": DocstringSectionKind.other_parameters,
   	"other args": DocstringSectionKind.other_parameters,
   	"other arguments": DocstringSectionKind.other_parameters,
   	"other params": DocstringSectionKind.other_parameters,
   	"other parameters": DocstringSectionKind.other_parameters,
   	"raises": DocstringSectionKind.raises,
   	"exceptions": DocstringSectionKind.raises,
   	"returns": DocstringSectionKind.returns,
   	"yields": DocstringSectionKind.yields,
   	"receives": DocstringSectionKind.receives,
   	"examples": DocstringSectionKind.examples,
   	"attributes": DocstringSectionKind.attributes,
   	"functions": DocstringSectionKind.functions,
   	"methods": DocstringSectionKind.functions,
   	"classes": DocstringSectionKind.classes,
   	"modules": DocstringSectionKind.modules,
   	"warns": DocstringSectionKind.warns,
   	"warnings": DocstringSectionKind.warns,
   	}

   I'm preparing a PR to address this. PR fix: Parse Deprecated sections in Google-style docstrings #353 addresses this issue.

To Reproduce (1 of 2)

Using mkdocstrings-python 1.13.0 (with MkDocs 1.6.1 and mkdocs-material 9.5.49) and griffe 1.5.4, the following Python function

def griffe_bug() -> None:
    """bla bla bla

    Deprecated:
        Since v1.0: Insecure! Do not use!
    """

renders as

Changing the section heading to DeprecatedABC changes the rendered admonition heading to "DeprecatedABC", confirming that this is indeed parsed as an admonition.

The tests in #353 confirm this suspicion as well.

Description of the bug (2 of 2)

If point (1) is fixed by adding the "deprecated" entry into the recognized section names table, then Griffe will assume the section contents are of the form version: text, and will attempt to partition the contents in this manner. If this fails, then Griffe will issue a warning, and then silently drop the entire section. This is because the parsing code, upon failing to partition the section text, returns None instead of a DocstringSection object (L711).

griffe/src/_griffe/docstrings/google.py

Lines 706 to 719 in a2f320f

	# 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,
	)

To Reproduce (2 of 2)

This is only confirmed via the tests in #353. No published version of Griffe exhibits this behavior yet.

Expected behavior

Griffe should parse these sections as Deprecated sections, not as admonitions. mkdocstrings-python should render them not as default admonitions, but as specific ones (perhaps similar to how griffe-deprecations renders them).

Griffe should not drop docstring sections it cannot properly parse, it should always pass them on.

Environment information

Debian Linux "testing", Python 3.12. See reproduction #1 above for Griffe and mkdocs* versions.

Additional context

(none)

[pawamoy]

Awesome report @the-13th-letter, thank you very much 🙂 I agree with everything. I'll review your PR now!