sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

[rst] Add `collapsible` option to admonition directives

Open chrisjsewell opened this issue 7 months ago • 25 comments

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:

  1. it is more user-friendly, since users do not have to learn any new extensions/directives, and can easily adapt current documentation
  2. 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

chrisjsewell avatar Jul 03 '24 14:07 chrisjsewell