feat: numpy admonitions

src/griffe/docstrings/numpy.py

@@ -34,6 +34,7 @@
     DocstringReceive,
     DocstringReturn,
     DocstringSection,
+    DocstringSectionAdmonition,
     DocstringSectionAttributes,
     DocstringSectionClasses,
     DocstringSectionDeprecated,
@@ -720,6 +721,19 @@ def _read_examples_section(
     return None, new_offset
 
 
+def _append_section(sections: list, current: list[str], admonition_title: str) -> None:
+    if admonition_title:
+        sections.append(
+            DocstringSectionAdmonition(
+                kind=admonition_title.lower().replace(" ", "-"),
+                text="\n".join(current).rstrip("\n"),
+                title=admonition_title,
+            ),
+        )
+    elif current and any(current):
+        sections.append(DocstringSectionText("\n".join(current).rstrip("\n")))
+
+
 _section_reader = {
     DocstringSectionKind.parameters: _read_parameters_section,
     DocstringSectionKind.other_parameters: _read_other_parameters_section,
@@ -762,6 +776,7 @@ def parse(
     """
     sections: list[DocstringSection] = []
     current_section = []
+    admonition_title = ""
 
     in_code_block = False
     lines = docstring.lines
@@ -787,32 +802,57 @@ def parse(
     while offset < len(lines):
         line_lower = lines[offset].lower()
 
+        # Code blocks can contain dash lines that we must not interpret.
         if in_code_block:
+            # End of code block.
             if line_lower.lstrip(" ").startswith("```"):
                 in_code_block = False
+            # Lines in code block must not be interpreted in any way.
             current_section.append(lines[offset])
 
-        elif line_lower in _section_kind and _is_dash_line(lines[offset + 1]):
-            if current_section:
-                if any(current_section):
-                    sections.append(DocstringSectionText("\n".join(current_section).rstrip("\n")))
-                current_section = []
-            reader = _section_reader[_section_kind[line_lower]]
-            section, offset = reader(docstring, offset=offset + 2, **options)  # type: ignore[operator]
-            if section:
-                sections.append(section)
-
+        # Start of code block.
         elif line_lower.lstrip(" ").startswith("```"):
             in_code_block = True
             current_section.append(lines[offset])
 
+        # Dash lines after empty lines lose their meaning.
+        elif _is_empty_line(lines[offset]):
+            current_section.append("")
+
+        # End of the docstring, wrap up.
+        elif offset == len(lines) - 1:
+            current_section.append(lines[offset])
+            _append_section(sections, current_section, admonition_title)
+            admonition_title = ""
+            current_section = []
+
+        # Dash line after regular, non-empty line.
+        elif _is_dash_line(lines[offset + 1]):
+            # Finish reading current section.
+            _append_section(sections, current_section, admonition_title)
+            current_section = []
+
+            # Start parsing new (known) section.
+            if line_lower in _section_kind:
+                admonition_title = ""
+                reader = _section_reader[_section_kind[line_lower]]
+                section, offset = reader(docstring, offset=offset + 2, **options)  # type: ignore[operator]
+                if section:
+                    sections.append(section)
+
+            # Start parsing admonition.
+            else:
+                admonition_title = lines[offset]
+                offset += 1  # skip next dash line
+
+        # Regular line.
         else:
             current_section.append(lines[offset])
 
         offset += 1
 
-    if current_section:
-        sections.append(DocstringSectionText("\n".join(current_section).rstrip("\n")))
+    # Finish current section.
+    _append_section(sections, current_section, admonition_title)
 
     return sections
 

tests/test_docstrings/test_numpy.py

@@ -114,6 +114,78 @@ def test_doubly_indented_lines_in_section_items(parse_numpy: ParserType) -> None
     assert lines[-1].startswith(4 * " " + "- ")
 
 
+# =============================================================================================
+# Admonitions
+def test_admonition_see_also(parse_numpy: ParserType) -> None:
+    """Test a "See Also" admonition.
+
+    Parameters:
+        parse_numpy: Fixture parser.
+    """
+    docstring = """
+    Summary text.
+
+    See Also
+    --------
+    some_function
+
+    more text
+    """
+
+    sections, _ = parse_numpy(docstring)
+    assert len(sections) == 2
+    assert sections[0].value == "Summary text."
+    assert sections[1].title == "See Also"
+    assert sections[1].value.description == "some_function\n\nmore text"
+
+
+def test_admonition_empty(parse_numpy: ParserType) -> None:
+    """Test an empty "See Also" admonition.
+
+    Parameters:
+        parse_numpy: Fixture parser.
+    """
+    docstring = """
+    Summary text.
+
+    See Also
+    --------
+    """
+
+    sections, _ = parse_numpy(docstring)
+    assert len(sections) == 2
+    assert sections[0].value == "Summary text."
+    assert sections[1].title == "See Also"
+    assert sections[1].value.description == ""
+
+
+def test_isolated_dash_lines_do_not_create_sections(parse_numpy: ParserType) -> None:
+    """An isolated dash-line (`---`) should not be parsed as a section.
+
+    Parameters:
+        parse_numpy: Fixture parser.
+    """
+    docstring = """
+    Summary text.
+
+    ---
+    Text.
+
+    Note
+    ----
+    Note contents.
+
+    ---
+    Text.
+    """
+
+    sections, _ = parse_numpy(docstring)
+    assert len(sections) == 2
+    assert sections[0].value == "Summary text.\n\n---\nText."
+    assert sections[1].title == "Note"
+    assert sections[1].value.description == "Note contents.\n\n---\nText."
+
+
 # =============================================================================================
 # Annotations
 def test_prefer_docstring_type_over_annotation(parse_numpy: ParserType) -> None: