Skip to content

Commit

Permalink
Add collapsible option to admonition directives (#12507)
Browse files Browse the repository at this point in the history 
This PR adds the `collapsible` and option to the core admonition type directives, which are propagated to the nodes, e.g.

```restructuredtext
.. admonition:: title
   :collapsible:

   content

.. note:: content
   :collapsible: closed
```

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.

```html
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>hallo</p>
</div>
```

changes to

```html
<details class="admonition note" open="open">
<summary class="admonition-title">Note</summary>
<p>hallo</p>
</details>
```

Co-authored-by: Adam Turner <[email protected]>
  • Loading branch information
@chrisjsewell @AA-Turner
chrisjsewell and AA-Turner authored Jan 29, 2025
1 parent 4936b27 commit 134bd7f
Show file tree
Hide file tree
Showing 11 changed files with 340 additions and 54 deletions.
3 changes: 3 additions & 0 deletions CHANGES.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------
Expand Down
106 changes: 83 additions & 23 deletions doc/_themes/sphinx13/static/sphinx13.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@
--icon-warning: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 14h-2v-4h2m0 8h-2v-2h2M1 21h22L12 2 1 21z"/></svg>');
--icon-failure: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2c5.53 0 10 4.47 10 10s-4.47 10-10 10S2 17.53 2 12 6.47 2 12 2m3.59 5L12 10.59 8.41 7 7 8.41 10.59 12 7 15.59 8.41 17 12 13.41 15.59 17 17 15.59 13.41 12 17 8.41 15.59 7z"/></svg>');
--icon-spark: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M11.5 20l4.86-9.73H13V4l-5 9.73h3.5V20M12 2c2.75 0 5.1 1 7.05 2.95C21 6.9 22 9.25 22 12s-1 5.1-2.95 7.05C17.1 21 14.75 22 12 22s-5.1-1-7.05-2.95C3 17.1 2 14.75 2 12s1-5.1 2.95-7.05C6.9 3 9.25 2 12 2z"/></svg>');

/* icons used for details summaries */
--icon-details-open: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8.59 16.58 13.17 12 8.59 7.41 10 6l6 6-6 6-1.41-1.42Z"/></svg>');
}

body {
Expand Down Expand Up @@ -409,7 +412,7 @@ table td, table th {
padding: 0.2em 0.5em 0.2em 0.5em;
}

div.admonition, div.warning {
div.admonition, div.warning, details.admonition {
font-size: 0.9em;
margin: 1em 0 1em 0;
border: 1px solid #86989B;
Expand All @@ -418,16 +421,16 @@ div.admonition, div.warning {
padding: 1rem;
}

div.admonition > p, div.warning > p {
div.admonition > p, div.warning > p, details.admonition > p {
margin: 0;
padding: 0;
}

div.admonition > pre, div.warning > pre {
div.admonition > pre, div.warning > pre, details.admonition > pre {
margin: 0.4em 1em 0.4em 1em;
}

div.admonition > p.admonition-title {
div.admonition > p.admonition-title, details.admonition > summary.admonition-title {
position: relative;
font-weight: 500;
background-color: var(--color-admonition-bg);
Expand All @@ -436,33 +439,78 @@ div.admonition > p.admonition-title {
border-radius: var(--admonition-radius) var(--admonition-radius) 0 0;
}

details.admonition:not([open]) {
padding-bottom: 0;
}
details.admonition > summary.admonition-title {
list-style: none;
cursor: pointer;
padding-right: .5rem;
}
details.admonition > summary.admonition-title::after {
background-color: currentcolor;
content: "";
height: 1.2rem;
width: 1.2rem;
-webkit-mask-image: var(--icon-details-open);
mask-image: var(--icon-details-open);
-webkit-mask-position: center;
mask-position: center;
-webkit-mask-repeat: no-repeat;
mask-repeat: no-repeat;
-webkit-mask-size: contain;
mask-size: contain;
transform: rotate(0deg);
transition: transform .25s;
float: right;
}
details.admonition[open] > summary.admonition-title::after {
transform: rotate(90deg);
}
details.admonition:not([open]) > summary.admonition-title {
margin-bottom: 0;
border-radius: var(--admonition-radius);
}

div.attention > p.admonition-title,
div.danger > p.admonition-title,
div.error > p.admonition-title {
div.error > p.admonition-title,
details.attention > summary.admonition-title,
details.danger > summary.admonition-title,
details.error > summary.admonition-title {
background-color: var(--colour-error-bg);
}

div.important > p.admonition-title,
div.caution > p.admonition-title,
div.warning > p.admonition-title {
div.warning > p.admonition-title,
details.important > summary.admonition-title,
details.caution > summary.admonition-title,
details.warning > summary.admonition-title {
background-color: var(--colour-warning-bg);
}

div.note > p.admonition-title {
div.note > p.admonition-title,
details.note > summary.admonition-title {
background-color: var(--colour-note-bg);
}

div.hint > p.admonition-title,
div.tip > p.admonition-title,
div.seealso > p.admonition-title {
div.seealso > p.admonition-title,
details.hint > summary.admonition-title,
details.tip > summary.admonition-title,
details.seealso > summary.admonition-title {
background-color: var(--colour-success-bg);
}

div.admonition-todo > p.admonition-title {
div.admonition-todo > p.admonition-title,
details.admonition-todo > summary.admonition-title {
background-color: var(--colour-todo-bg);
}

p.admonition-title::before {
p.admonition-title::before,
summary.admonition-title::before {
content: "";
height: 1rem;
left: .5rem;
Expand All @@ -472,69 +520,81 @@ p.admonition-title::before {
background-color: #5f5f5f;
}

div.admonition > p.admonition-title::before {
div.admonition > p.admonition-title::before,
details.admonition > summary.admonition-title::before {
background-color: var(--color-admonition-fg);
-webkit-mask-image: var(--icon-abstract);
mask-image: var(--icon-abstract);
}
div.attention > p.admonition-title::before {
div.attention > p.admonition-title::before,
details.attention > summary.admonition-title::before {
background-color: var(--colour-error-fg);
-webkit-mask-image: var(--icon-warning);
mask-image: var(--icon-warning);
}
div.caution > p.admonition-title::before {
div.caution > p.admonition-title::before,
details.caution > summary.admonition-title::before {
background-color: var(--colour-warning-fg);
-webkit-mask-image: var(--icon-spark);
mask-image: var(--icon-spark);
}
div.danger > p.admonition-title::before {
div.danger > p.admonition-title::before,
details.danger > summary.admonition-title::before {
background-color: var(--colour-error-fg);
-webkit-mask-image: var(--icon-spark);
mask-image: var(--icon-spark);
}
div.error > p.admonition-title::before {
div.error > p.admonition-title::before,
details.error > summary.admonition-title::before {
background-color: var(--colour-error-fg);
-webkit-mask-image: var(--icon-failure);
mask-image: var(--icon-failure);
}
div.hint > p.admonition-title::before {
div.hint > p.admonition-title::before,
details.hint > summary.admonition-title::before {
background-color: var(--colour-success-fg);
-webkit-mask-image: var(--icon-question);
mask-image: var(--icon-question);
}
div.important > p.admonition-title::before {
div.important > p.admonition-title::before,
details.important > summary.admonition-title::before {
background-color: var(--colour-warning-fg);
-webkit-mask-image: var(--icon-flame);
mask-image: var(--icon-flame);
}
div.note > p.admonition-title::before {
div.note > p.admonition-title::before,
details.note > summary.admonition-title::before {
background-color: var(--colour-note-fg);
-webkit-mask-image: var(--icon-pencil);
mask-image: var(--icon-pencil);
}
div.seealso > p.admonition-title::before {
div.seealso > p.admonition-title::before,
details.seealso > summary.admonition-title::before {
background-color: var(--colour-success-fg);
-webkit-mask-image: var(--icon-info);
mask-image: var(--icon-info);
}
div.tip > p.admonition-title::before {
div.tip > p.admonition-title::before,
details.tip > summary.admonition-title::before {
background-color: var(--colour-success-fg);
-webkit-mask-image: var(--icon-info);
mask-image: var(--icon-info);
}
div.admonition-todo > p.admonition-title::before {
div.admonition-todo > p.admonition-title::before,
details.admonition-todo > summary.admonition-title::before {
background-color: var(--colour-todo-fg);
-webkit-mask-image: var(--icon-pencil);
mask-image: var(--icon-pencil);
}
div.warning > p.admonition-title::before {
div.warning > p.admonition-title::before,
details.warning > summary.admonition-title::before {
background-color: var(--colour-warning-fg);
-webkit-mask-image: var(--icon-warning);
mask-image: var(--icon-warning);
}
div.caution,
div.important,
div.warning {
div.warning, details.warning {
border-color: var(--colour-warning-fg);
}
div.attention,
Expand Down
50 changes: 50 additions & 0 deletions doc/usage/restructuredtext/directives.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -480,6 +480,56 @@ and the generic :rst:dir:`admonition` directive.
Documentation for tar archive files, including GNU tar extensions.


.. _collapsible-admonitions:

.. rubric:: Collapsible text

.. versionadded:: 8.2

Each admonition directive supports a ``:collapsible:`` option,
to make the content of the admonition collapsible
(where supported by the output format).
This can be useful for content that is not always relevant.
By default, collapsible admonitions are initially open,
but this can be controlled with the ``open`` and ``closed`` arguments
to the ``:collapsible:`` option, which change the default state.
In output formats that don't support collapsible content,
the text is always included.
For example:

.. code-block:: rst
.. 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.
.. 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.


Describing changes between versions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down
1 change: 1 addition & 0 deletions sphinx/application.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@
'sphinx.domains.rst',
'sphinx.domains.std',
'sphinx.directives',
'sphinx.directives.admonitions',
'sphinx.directives.code',
'sphinx.directives.other',
'sphinx.directives.patches',
Expand Down
Loading

0 comments on commit 134bd7f

Please sign in to comment.