numpydoc sections not represented as its own block, if first in docstring

[machow]

Describe the bug

For a function with a docstring like this:

def f():
    """
    one liner, this isn't shown

    longer description, this isn't shown

    See Also
    --------
    [related function, this is shown](#related_function)
    """

griffe's numpydoc parses produces a single DocstringSectionText, with all the contents.

WDYT of editing this line of the numpydoc parse, to ensure any section marked with lines (----) is its own DocstringSectionText?

https://github.com/mkdocstrings/griffe/blob/main/src/griffe/docstrings/numpy.py#L816

This way, various sections like See Also will be in their own DocstringSectionText, regardless of whether they're...

• sandwiched between two sections that are parsed (e.g. Parameters and Returns)
• the first section of the docstring
• after another section of docstring that doesn't get parsed

[pawamoy]

Definitely looks like a bug in the parser! Also, yeah, I was planning to add support for generic admonitions, just like in the Google parser.

[machow]

I can work on a quick PR tomorrow for the numpydoc parser! Is DocstringSectionAdmonition the catch-all for unknown sections? I think because I focused initially on numpydoc format in quartodoc, I totally missed that this piece existed in the google style parser 😅

(guessing from this google parser line)

[pawamoy]

Is DocstringSectionAdmonition the catch-all for unknown sections?

Yes!

A PR would be awesome, thanks a lot :)