1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
(usage)=
# Use and configure
This page covers how to use and configure / customize `sphinx-togglebutton`.
There are three main ways to use `sphinx-togglebutton`:
- Wrap arbitrary objects in a toggle button via a CSS selector
- Collapse admonitions with the `dropdown` class
- Make arbitrary chunks of content "toggle-able" with the `toggle` directive
Each is described below
(use:css-selector)=
## Collapse a block of content with a CSS selector
You can hide any content and display a toggle button to show it by using certain CSS classes.
`sphinx-togglebutton` will wrap elements with these classes in a `<details>` block like so:
```html
<details>
<summary>Click to show</summary>
<!-- Element that had a CSS class selector -->
</details>
```
````{example}
```{image} https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif
:class: toggle
```
````
### Configure the CSS selector used to insert toggle buttons
By default, `sphinx-togglebutton` will use this selector:
```
.toggle, .admonition.dropdown
```
However, you can customize this behavior with the `togglebutton_selector` configuration value.
To specify the selector to use, pass a valid CSS selector as a string:
:::{admonition} example
:class: tip
Configure `sphinx-togglebutton` to look for a `.toggle-this-element` class and an element with ID `#my-special-id` **instead of** `.toggle` and `.admonition.dropdown`.
```python
sphinx_togglebutton_selector = ".toggle-this-element, #my-special-id"
```
:::
(dropdown-admonitions)=
## Collapse admonitions with the `dropdown` class
`sphinx-togglebutton` treats admonitions as a special case if they are selected.
If a Sphinx admonition matches the toggle button selector, then its title will be displayed with a button to reveal its content.
````{example}
```{admonition} This will be shown
:class: dropdown
And this will be hidden!
```
````
This works for any kind of Sphinx admoniton:
:::{note}
:class: dropdown
A note!
:::
:::{warning}
:class: dropdown
A warning!
:::
(toggle-directive)=
## Use the `{toggle}` directive to toggle blocks of content
To add toggle-able content, use the **toggle directive**. This directive
will wrap its content in a toggle-able container. You can call it like so:
:::{tab-set-code}
````markdown
```{toggle}
Here is my toggle-able content!
```
````
```rst
.. toggle::
Here is my toggle-able content!
```
:::
The code above results in:
:::{toggle}
Here is my toggle-able content!
:::
To show the toggle-able content by default, use the `:show:` flag.
````markdown
```{toggle}
:show:
Here is my toggle-able content!
```
````
It results in the following:
:::{toggle}
:show:
Here is my toggle-able content!
:::
## Change the button hint text
You can control the "hint" text that is displayed next to togglebuttons.
To do so, use the following configuration variable in your `conf.py` file:
```python
togglebutton_hint = "Displayed when the toggle is closed."
togglebutton_hint_hide = "Displayed when the toggle is open."
```
## Change the toggle icon color
You can apply some extra styles to the toggle button to achieve the look you want.
This is particularly useful if the color of the toggle button does not contrast with the background of an admonition.
To style the toggle button, [add a custom CSS file to your documentation](https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html) and include a custom CSS selector like so:
```scss
// Turn the color red...
// ...with admonition toggle buttons
button.toggle-button {
color: red;
}
// ...with content block toggle buttons
.toggle-button summary {
color: red;
}
```
## Printing behavior with toggle buttons
By default `sphinx-togglebutton` will **open all toggle-able content when you print**.
It will close them again when the printing operation is complete.
To disable this behavior, use the following configuration in `conf.py`:
```python
togglebutton_open_on_print = False
```
|
