sphinx
sphinx copied to clipboard
[rst] Add `collapsible` option to admonition directives
edit: see https://sphinx--12507.org.readthedocs.build/en/12507/usage/restructuredtext/directives.html#directive-note, for an example usage and rendering
This PR adds collapsible
and open
flag options to the core admonition type directives, which are propagated to the nodes, e.g.
.. admonition:: title
:collapsible:
:open:
content
.. note:: content
:collapsible:
:open:
For the HTML5 writer, this replaces the outer div
with a details
tag, and the title p
with a summary
tag (with an open
attribute if set), e.g.
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>hallo</p>
</div>
<details class="admonition note" open="open">
<summary class="admonition-title">Note</summary>
<p>hallo</p>
</details>
For all other writers, these attributes are ignored.
I feel this a better alternative to #10532, since:
- it is more user-friendly, since users do not have to learn any new extensions/directives, and can easily adapt current documentation
- it still fits into the conceptual model of an “abstract document”, since no new (HTML-only) nodes are added
This would inherently require additions to theme extensions, to correctly style such admonitions.
But I feel this would be worth the effort (and already necessary anyway for #10532), (in fact, it has already been added in https://jbms.github.io/sphinx-immaterial/admonitions.html#directive-option-admonition-collapsible, which in-turn mirrors https://squidfunk.github.io/mkdocs-material/reference/admonitions/#collapsible-blocks)
cc @pradyunsg for comment
TODO: tests, documentation, addition of CSS styling to core/docs theme