sphinx-togglebutton¶

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

Collapse admonitions (notes, warnings, etc) so that their content is hidden until users click a toggle button. See Dropdown admonitions by adding classes.
Collapse arbitrary chunks of content on your page with a toggle directive. See Toggle any content with the toggle directive.

For example, click the “+” button to the right:

Here’s a toggled note! You can put all kinds of stuff in here!

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!

Dropdown admonitions by adding classes¶

Making dropdown admonitions allows you to insert extra information in your document without forcing the user to see that content. For example:

What could be inside this warning?

A whale of a joke!

https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif

(sorry)

Create a dropdown admonition by adding the dropdown class to an admonition directive. For example, like so:

.. note::
   :class: dropdown

   My note

Note that you can use a custom admonition title and apply the style of a “built-in” admonition (e.g., note, warning, etc) with the admonition:: directive:

.. admonition:: Here's my title
   :class: dropdown, warning

   My note

Creates:

Here’s my title

My custom admonition!

To show the content by default, add a toggle-shown class as well.

.. note::
    :class: dropdown, toggle-shown

    This is my note.

This will generate the following block:

Note

This is my note.

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.

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

Admonition content.