sphinx-togglebutton

A small sphinx extension to make it possible to add a “toggle button” to sections of your page. This allows you to:

You can also add a toggle button to arbitrary chunks of content. For example, click the toggle button to the right just below.

Wow!

It’s a code block!

a = "wow, very python"

See Usage for more information.

Check out sphinx-panels as well!

For a bootstrap-based “dropdown” directive that uses pure CSS, check out Sphinx Panels

Installation

You can install sphinx-togglebutton with pip:

pip install sphinx-togglebutton

Then, activate it in your sphinx build by adding it to your conf.py configuration file, like so:

E.g.:

extensions = [
    ...
    'sphinx_togglebutton'
    ...
]

See Usage for information about how to use sphinx-togglebutton.

Usage

There are two main ways to use sphinx-togglebutton:

  • Collapse admonitions with the dropdown class

  • Make arbitrary chunks of content “toggle-able” with the toggle:: directive

Caution

sphinx-togglebutton is designed for the sphinx-book-theme. It should work properly on other themes, but if you notice any CSS bugs, please open an issue!

Toggle any content with the toggle directive

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:

.. toggle::

    Here is my toggle-able content!

The code above results in:

Here is my toggle-able content!

To show the toggle-able content by default, use the :show: flag.

.. toggle::
    :show:

    Here is my toggle-able content!

It results in the following:

Here is my toggle-able content!

Configuration

Below are a few configuration points for sphinx-togglebutton.

Control the togglebutton hover text

You can control the “hint” text that is displayed next to togglebuttons when their content is collapsed. To do so, use the following configuration variable in your conf.py file:

togglebutton_hint = "My text"

Reference

This is a simple reference section to double-check styling etc.

Here’s how they look right after one another:

Note

This is my note.

Note

This is my second.

This is my first.

This is my second.

A really long admonition that will take up multiple lines A really long admonition that will take up multiple lines

Admonition content.

https://jupyterbook.org/_static/logo.png

A really long admonition that will take up multiple lines A really long admonition that will take up multiple lines

Admonition content.

https://jupyterbook.org/_static/logo.png