bug: MkDocs !!! and ??? admonitions can no longer be parsed about griffe

[parafoxia]

This is linked to parafoxia/analytix#61 (pawamoy responded to that as I was writing this!).

[pawamoy]

Nice timing haha!

So, for reference (stated in the linked issue):

• recent changes to our Numpydoc parser made it so that prose after sections is not allowed anymore (this makes us more compliant with Numpydoc's official style-guide which does not explicitly allow that)
• !!! and ??? blocks are Markdown markup, and therefore what we call prose, and that's why these cannot be parsed after known sections such as Parameters or Returns anymore
• instead, users can take advantage of the new parser capabilities, generic admonitions:

!!! note
    Hello.

...becomes:

Note
----
Hello.

• finally, note that it is still possible to use Markdown markup in all the other places it was also supported: in section item descriptions, as well as in the non-section body of the docstring:

Summary.

Body. Markup still allowed here:

!!! note
    Working.

Parameters
----------
param1
    Description of param1.

    !!! warning
        Warning about param1.

param2
    etc.

The new admonitions can use any title, and their kind is inferred from the title (basically slugified title):

• Note
  ----
  Hello.
  

  gives title=Note, kind=note

• See also
  --------
  Something.
  

  gives title=See also, kind=see-also

I realize there's no way to specify the kind and title separately. Maybe the logic could be improved here to support things like:

Warning: Pay attention to something
-----------------------------------
Contents.

...giving kind=warning, title=Pay attention to something. @machow what do you think?

[pawamoy]

I will close this issue but pin it for some time, in case others are impacted by the change.