feature: Render admonitions as non-collapsible blocks

[antonymilne]

Is your feature request related to a problem? Please describe.

Thank you for the great little package, it's very handy! Currently the deprecation admonition is rendered as a collapsible block. This looks a little odd to me given that the warning message inside is usually just one line long.

Describe the solution you'd like

A way to specify the block as non-collapsible, presumably a setting in the configuration for the plugin:

      extensions:
      - griffe_warnings_deprecated:
          title: null
          kind: warning
          collapsible: false # or something like that

Describe alternatives you've considered

• Manually do the warning with !!! rather than ??? but that defeats the point of these warnings being automatically generated.
• Disable pymdownx.details for certain docs pages/sections? Not even sure if that's possible.

Additional context

I'd be happy to contribute a PR to add this functionality if you could give me a hint about what you'd like the configuration syntax to be (e.g. allow collapsible on/off or expanded/collapsed by default?) and how to actually implement it 😅 Because at a quick glance at the code it seems like DocstringSectionAdmonition doesn't have a collapse/expand argument (I guess that behaviour is purely controlled by the pymdownx.details plugin?) so maybe this is just not possible...

FYI @maxschulz-COL

[pawamoy]

Thanks for the feature request @antonymilne 🙂 Admonitions are rendered as details HTML elements by mkdocstrings-python. Then these details are styled by the theme (usually Material for MkDocs). If we wanted to create non-collapsible admonitions (given they provide such metadata), we'd have to use plain div elements with an admonition CSS class. Initially I didn't want to use that because it felt much more dependent to Material for MkDocs, and less generally supported by themes. But we're really targetting this theme so why not allow that in the end.

To summarize, for this to happen, we would have to:

• update the admonition template in mkdocstrings-python, to render <details class="..."> or <div class="admonition ..."> depending on one or both of:
  1. a collapsible attribute on the admonition object
  2. automatic behavior by making them non-collapsible if there's only a title
• if option 1 above is accepted, the admonition docstring model in Griffe should be updated to hold this collapsible attribute, and perhaps a collapsed attribute too (to decide whether the admonition is initially open or collapsed)
• finally, this extension could be updated to make use of these new attributes, exposing them as options to users

[antonymilne]

Thanks for clarifying @pawamoy! I'm never sure of the relationship between Material, mkdocs, mkdocstrings-python or other extensions or exactly what's responsible for what 😅

[pawamoy]

Yeah it's quite a mesh of projects 😄