Add collapsible option to admonition directives

CHANGES.rst

@@ -88,6 +88,9 @@ Features added
 * #13271: Support the ``:abstract:`` option for
   classes, methods, and properties in the Python domain.
   Patch by Adam Turner.
+* #12507: Add the :ref:`collapsible <collapsible-admonitions>` option
+  to admonition directives.
+  Patch by Chris Sewell.
 
 Bugs fixed
 ----------

doc/usage/restructuredtext/directives.rst

@@ -484,6 +484,8 @@ and the generic :rst:dir:`admonition` directive.
 
 .. rubric:: Collapsible text
 
+.. versionadded:: 8.2.0
+
 Each admonition directive supports a ``:collapsible:`` option,
 to make the content of the admonition collapsible
 (where supported by the output format).

tests/roots/test-directives-admonition-collapse/index.rst

@@ -0,0 +1,22 @@
+test-directives-admonition-collapse
+===================================
+
+.. note::
+   :class: standard
+
+   This is a standard note.
+
+.. note::
+   :collapsible:
+
+   This note is collapsible, and initially open by default.
+
+.. admonition:: Example
+   :collapsible: open
+
+   This example is collapsible, and initially open.
+
+.. hint::
+   :collapsible: closed
+
+   This hint is collapsible, but initially closed.

tests/test_builders/test_build_html.py

@@ -715,3 +715,47 @@ def __call__(self, nodes):
         r'.//dt[@id="MyList"][1]',
         chk('class MyList[\nT\n](list[T])'),
     )
+
+
+@pytest.mark.sphinx('html', testroot='directives-admonition-collapse')
+def test_html_admonition_collapse(app):
+    app.build()
+    fname = app.outdir / 'index.html'
+    etree = etree_parse(fname)
+
+    def _create_check(text: str, open: bool):  # type: ignore[no-untyped-def]
+        def _check(els):
+            assert len(els) == 1
+            el = els[0]
+            if open:
+                assert el.attrib['open'] == 'open'
+            else:
+                assert 'open' not in el.attrib
+            assert el.find('p').text == text
+
+        return _check
+
+    check_xpath(
+        etree,
+        fname,
+        r'.//div[@class="standard admonition note"]//p',
+        'This is a standard note.',
+    )
+    check_xpath(
+        etree,
+        fname,
+        r'.//details[@class="admonition note"]',
+        _create_check('This note is collapsible, and initially open by default.', True),
+    )
+    check_xpath(
+        etree,
+        fname,
+        r'.//details[@class="admonition-example admonition"]',
+        _create_check('This example is collapsible, and initially open.', True),
+    )
+    check_xpath(
+        etree,
+        fname,
+        r'.//details[@class="admonition hint"]',
+        _create_check('This hint is collapsible, but initially closed.', False),
+    )