Add special case for NumpyDoc warnings section so they render as warning admonitions

[parafoxia]

This PR fixes a bug in the NumpyDoc parser where the Warnings section would render as a note admonition. They now render as warning admonitions.

I felt bad opening an issue about this after accusing the NumpyDoc parser of being buggy yesterday, so thought I'd at least contribute this one myself 😄

[parafoxia]

I'm not sure what the deal with the (macos-latest, 3.8) tests is, but I don't think that's my fault? 😅

[pawamoy]

Indeed, not sure what these /var / /private/var shenanigans are.

Regarding the change: I don't like modifying kinds in the generic admonition class. Ideally, Griffe is never aware of how admonition kinds are used, which ones are available, etc. It all depends on the downstream docs system. For all we know, maybe someone has defined a custom warnings (plural) admonition that differs from a warning (singular) one. Or maybe other docstring styles allow such plural kinds.

With this in mind, I'd prefer that we handle this special case in the Numpy parser itself, rather than in the generic admonition class, and only because Warnings section are actually specified in the style-guide (https://numpydoc.readthedocs.io/en/latest/format.html#warnings).

Looks like _append_section would be the right place for that:

def _append_section(sections: list, current: list[str], admonition_title: str) -> None:
    if admonition_title:
        kind = admonition_title.lower().replace(" ", "-")
        # Numpydoc style-guide defines a Warnings section,
        # so we special-case it here to avoid breaking user expectations.
        if kind == "warnings":
            kind = "warning"
        sections.append(
            DocstringSectionAdmonition(
                kind=kind,
                text="\n".join(current).rstrip("\n"),
                title=admonition_title,
            ),
        )
    elif current and any(current):
        sections.append(DocstringSectionText("\n".join(current).rstrip("\n")))

WDYT?

By the way, maybe we should also modify notes into note. It works in MkDocs because code responsible for admonitions defaults to the note style when the kind is unknown, but maybe that's not the case in other systems.

[parafoxia]

Wrote this comment, made the changes, then realised I forgot to press send lmao. I like your suggestion though, didn't realise there were NumpyDoc specific sections so deffo better to handle the special cases in those. I've also added a special case for the Notes section as well.

[pawamoy]

OK, LGTM! Just two suggestions that I'll commit right away, and we can merge 🙂

[parafoxia]

Leaving the branch up as I need to build the docs from it until the next Griffe version is released.

[pawamoy]

I wanted to pack a few more things in the next release, but they've been delayed, so I'll release one today 🙂

[pawamoy]

v0.41.0 released.

[parafoxia]

Awesome, thanks! 🎉