feat: Add ignore_init_summary option to the Google parser

src/griffe/docstrings/google.py

@@ -497,6 +497,7 @@ def _is_empty_line(line) -> bool:
 
 def parse(  # noqa: WPS231
     docstring: Docstring,
+    ignore_init_summary: bool = False,
     **options: Any,
 ) -> list[DocstringSection]:
     """Parse a docstring.
@@ -506,6 +507,7 @@ def parse(  # noqa: WPS231
 
     Parameters:
         docstring: The docstring to parse.
+        ignore_init_summary: Whether to ignore the summary in `__init__` methods' docstrings.
         **options: Additional parsing options.
 
     Returns:
@@ -515,9 +517,21 @@ def parse(  # noqa: WPS231
     current_section = []
 
     in_code_block = False
-
     lines = docstring.lines
-    offset = 0
+
+    ignore_summary = (
+        ignore_init_summary  # noqa: WPS222
+        and docstring.parent is not None
+        and docstring.parent.name == "__init__"
+        and docstring.parent.is_function
+        and docstring.parent.parent is not None
+        and docstring.parent.parent.is_class
+    )
+
+    if ignore_summary:
+        offset = 2
+    else:
+        offset = 0
 
     while offset < len(lines):
         line_lower = lines[offset].lower()

src/griffe/docstrings/parsers.py

@@ -48,5 +48,5 @@ def parse(docstring: Docstring, parser: Parser | None, **options: Any) -> list[D
         A list of docstring sections.
     """
     if parser:
-        return parsers[parser](docstring, **options)
+        return parsers[parser](docstring, **options)  # type: ignore[operator]
     return [DocstringSection(DocstringSectionKind.text, docstring.value)]

tests/test_docstrings/test_google.py

@@ -6,7 +6,7 @@
 
 import pytest
 
-from griffe.dataclasses import Function, Parameter, Parameters
+from griffe.dataclasses import Class, Function, Module, Parameter, Parameters
 from griffe.docstrings import google
 from griffe.docstrings.dataclasses import DocstringSectionKind
 from tests.test_docstrings.helpers import parser
@@ -720,3 +720,35 @@ def test_handle_false_admonitions_correctly(docstring):
     assert sections[0].kind is DocstringSectionKind.text
     assert len(sections[0].value.splitlines()) == len(inspect.cleandoc(docstring).splitlines())
     assert not warnings
+
+
+@pytest.mark.parametrize(
+    "docstring",
+    [
+        "",
+        "\n",
+        "\n\n",
+        "Summary.",
+        "Summary.\n\n\n",
+        "Summary.\n\nParagraph.",
+        "Summary\non two lines.",
+        "Summary\non two lines.\n\nParagraph.",
+    ],
+)
+def test_ignore_init_summary(docstring):
+    """Correctly ignore summary in `__init__` methods' docstrings.
+
+    Parameters:
+        docstring: The docstring to parse (parametrized).
+    """
+    sections, _ = parse(docstring, parent=Function("__init__", parent=Class("C")), ignore_init_summary=True)
+    for section in sections:
+        assert "Summary" not in section.value
+
+    if docstring.strip():
+        sections, _ = parse(docstring, parent=Function("__init__", parent=Module("M")), ignore_init_summary=True)
+        assert "Summary" in sections[0].value
+        sections, _ = parse(docstring, parent=Function("f", parent=Class("C")), ignore_init_summary=True)
+        assert "Summary" in sections[0].value
+        sections, _ = parse(docstring, ignore_init_summary=True)
+        assert "Summary" in sections[0].value