Sphinx Toggle Button

0.4.5 · active · verified Tue Apr 14

Sphinx Toggle Button is a Sphinx extension that enables users to add toggle functionality to documentation, allowing them to collapse or expand sections of content and admonitions. The library is actively maintained, with frequent patch releases addressing fixes and minor releases introducing new features. The current version is 0.4.5.

Warnings

breaking The v0.3.0 and v0.3.2 releases introduced significant visual changes to the toggle buttons and icons. Custom CSS styling targeting older versions (pre-0.3.0) may need adjustment, as the design and layout of the toggle elements were overhauled.
Fix: Review your custom CSS for selectors targeting sphinx-togglebutton elements and update them to match the new HTML structure introduced in v0.3.0. Refer to the official documentation for the latest CSS classes and structure.
gotcha By default, `sphinx-togglebutton` applies toggle functionality to elements matching `.toggle` or `.admonition.dropdown` CSS selectors. If you wish to apply toggles to other custom elements or classes, you must explicitly configure the `togglebutton_selector` in `conf.py`.
Fix: To customize the target selectors, add `togglebutton_selector = ".my-custom-class, #my-id"` to your `conf.py`.
gotcha When a Sphinx documentation page containing toggle buttons is printed, all toggle-able content is opened by default. This might not be the desired behavior for all use cases.
Fix: To disable this automatic expansion on print, set `togglebutton_open_on_print = False` in your `conf.py` file.

Install

pip install sphinx-togglebutton Install latest version

Imports

Extension Configuration
```
extensions = ['sphinx_togglebutton'] # in conf.py
```
sphinx-togglebutton is a Sphinx extension, not a Python module imported into application code. It's added to the 'extensions' list in Sphinx's conf.py.

Quickstart

To enable sphinx-togglebutton, add 'sphinx_togglebutton' to the `extensions` list in your Sphinx project's `conf.py` file. Once enabled, you can make admonitions collapsible by adding `:class: dropdown` to them, or hide arbitrary blocks of content using the `.. toggle::` directive.

# conf.py
extensions = [
    'sphinx_togglebutton',
    # ... other extensions
]

# example.rst or example.md

.. note:: Click to toggle
   :class: dropdown

   This content is initially hidden and can be toggled by clicking the admonition title.


.. toggle:: Show/Hide Arbitrary Content

   This entire block of content, including paragraphs and other directives,
   will be hidden behind a toggle button.

   - Item 1
   - Item 2

view raw JSON →