feat: numpy admonitions

src/griffe/docstrings/numpy.py

@@ -34,6 +34,7 @@
     DocstringReceive,
     DocstringReturn,
     DocstringSection,
+    DocstringSectionAdmonition,
     DocstringSectionAttributes,
     DocstringSectionClasses,
     DocstringSectionDeprecated,
@@ -782,7 +783,9 @@ def parse(
     """
     sections: list[DocstringSection] = []
     current_section = []
+    current_title = None
 
+    in_section_marker = False
     in_code_block = False
     lines = docstring.lines
 
@@ -806,35 +809,63 @@ def parse(
     offset = 2 if ignore_summary else 0
 
     while offset < len(lines):
+        is_end = offset == len(lines) - 1
         line_lower = lines[offset].lower()
 
-        if in_code_block:
-            if line_lower.lstrip(" ").startswith("```"):
-                in_code_block = False
-            current_section.append(lines[offset])
+        # mark code blocks, since they can contain section markers
+        if line_lower.lstrip(" ").startswith("```"):
+            in_code_block = not in_code_block
 
-        elif line_lower in _section_kind and _is_dash_line(lines[offset + 1]):
-            if current_section:
-                if any(current_section):
+        if is_end or (
+            not in_code_block
+            and not in_section_marker
+            and line_lower
+            and _is_dash_line(lines[offset + 1])
+        ):
+            # create previous section ----
+            if is_end and not in_section_marker:
+                current_section.append(lines[offset])
+
+            if current_section or current_title:
+                # this should apply to most section, except for the initial summary,
+                # which does not have a title. however, due to how the reader() parses
+                # numpydoc specification sections, and when it decides to terminate,
+                # there could be other sections without a title.
+                if current_title is not None:
+                    sections.append(DocstringSectionAdmonition(
+                        kind=current_title.replace(" ", "-"),
+                        text="\n".join(current_section).rstrip("\n"),
+                        title=current_title
+                    ))
+                # create generic text sections. note that these might include anything
+                # "between" two parsed sections. for example, if a parameters section
+                # table has free text beneath it.
+                elif any(current_section) or is_end:
                     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)
+                current_title = lines[offset].strip()
+
+            # handle new section ----
+            if line_lower in _section_kind:
+                reader = _section_reader[_section_kind[line_lower]]
+                section, offset = reader(docstring, offset=offset + 2, **options)  # type: ignore[operator]
+                if section:
+                    sections.append(section)
+
+                current_title = None
+            else:
+                # ensure we don't add the dashed lines as content next loop
+                in_section_marker = True
 
-        elif line_lower.lstrip(" ").startswith("```"):
-            in_code_block = True
+        elif not in_section_marker:
             current_section.append(lines[offset])
 
         else:
-            current_section.append(lines[offset])
+            in_section_marker = False
 
         offset += 1
 
-    if current_section:
-        sections.append(DocstringSectionText("\n".join(current_section).rstrip("\n")))
-
     return sections
 
 

tests/test_docstrings/test_numpy.py

@@ -119,6 +119,88 @@ def test_doubly_indented_lines_in_section_items(parse_numpy: ParserType) -> None
     assert lines[-1].startswith(4 * " " + "- ")
 
 
+def test_text_section_after_parameters(parse_numpy: ParserType) -> None:
+    docstring = """
+        Parameters
+        ----------
+        a:
+            Some description
+
+        A new text section
+    """
+
+    sections, _ = parse_numpy(docstring)
+    assert len(sections) == 2
+    assert sections[1].value == "A new text section"
+
+
+def test_text_section_between_sections(parse_numpy: ParserType) -> None:
+    docstring = """
+        Parameters
+        ----------
+        a:
+            Some description
+
+        A new text section
+
+        Returns
+        -------
+        x: int
+    """
+
+    sections, _ = parse_numpy(docstring)
+    assert len(sections) == 3
+    assert sections[1].value == "A new text section"
+
+
+# =============================================================================================
+# Admonitions
+
+def test_admonition_see_also(parse_numpy: ParserType) -> None:
+    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:
+    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_admonition_empty_title_is_text_section(parse_numpy: ParserType) -> None:
+    docstring = """
+    Summary text.
+
+    ---
+    """
+
+    sections, _ = parse_numpy(docstring)
+    assert len(sections) == 1
+    assert sections[0].value == "Summary text.\n\n---"
+
+
 # =============================================================================================
 # Annotations
 def test_prefer_docstring_type_over_annotation(parse_numpy: ParserType) -> None: