Skip to content

using classes for admonition toggles #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 9, 2020
Merged

using classes for admonition toggles #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 5 additions & 8 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,6 @@
# ones.
extensions = ["myst_nb", "sphinx_togglebutton"]

togglebutton_selector = ".toggle, .toggle-this-item"

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

Expand Down Expand Up @@ -76,13 +74,12 @@
# a list of builtin themes.
#
html_theme = "sphinx_book_theme"
# html_theme = 'sphinx_rtd_theme'
# html_theme = "sphinx_rtd_theme"
# html_theme = "alabaster"

# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
html_theme_options = {
"single_page": True,
}

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
Expand Down
191 changes: 93 additions & 98 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,32 @@ sphinx-togglebutton
A small sphinx extension to make it possible to add a "toggle button" to
sections of your page.

For example, click the "+" button to the right:
.. admonition:: For example, click the "+" button to the right:
:class: dropdown

.. toggle::

.. note:: Here's a toggled admonition

It was created with this code:
Here's a toggled note! You can put all kinds of stuff in here!

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

.. toggle::
.. toggle::

.. note:: Here's a toggled admonition
.. admonition:: Wow!
:class: tip

You can also add a title to your toggled block. The title will show up,
and the toggle button will change the block's content. For example:
It's a code block!

.. toggle:: Toggle to see what's inside
.. code-block:: python

It's a code block!
a = "wow, very python"

.. code-block:: python
See :ref:`usage` for more information.

a = "wow, very python"
print("this code should be toggle-able!")
.. caution::

``sphinx-togglebutton`` is designed for the
`sphinx-book-theme <https://sphinx-book-theme.readthedocs.io/>`_. It should work
properly on other themes, but if you notice any CSS bugs, please open an issue!

Installation
============
Expand All @@ -41,12 +41,8 @@ You can install `sphinx-togglebutton` with `pip`:

pip install sphinx-togglebutton


Usage
=====

In your ``conf.py`` configuration file, add ``sphinx_togglebutton``
to your extensions list.
Then, activate it in your ``sphinx`` build by adding it to your ``conf.py`` configuration
file, like so:

E.g.:

Expand All @@ -58,110 +54,113 @@ E.g.:
...
]

See :ref:`usage` for information about how to use ``sphinx-togglebutton``.

The toggle directive
--------------------
.. _usage:

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:
Usage
=====

.. code-block:: rst
There are two main ways to use ``sphinx-togglebutton``:

.. toggle::
* Create dropdown admonitions with the ``dropdown`` class
* Make arbitrary chunks of content "toggle-able" with the ``toggle::`` directive

Here is my toggle-able content!
.. _dropdown-admonitions:

The code above results in:
Dropdown admonitions by adding classes
--------------------------------------

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

Here is my toggle-able content!
.. admonition:: What could be inside this warning?
:class: warning, dropdown

You can also add titles to your toggle-able content:
A whale of a joke!

.. code-block:: rst
.. image:: https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif

.. toggle:: My title
(sorry)

Here is my toggle-able content!
Create a dropdown admonition by adding the ``dropdown`` class to an admonition directive.
For example, like so:

Which results in:
.. code-block:: rst

.. note::
:class: dropdown

.. toggle:: My title
My note

Here is my toggle-able content!

To show the toggle-able content by default, use the ``:show:`` flag.
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:

.. code-block:: rst

.. toggle::
:show:

Here is my toggle-able content!

It results in the following:

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

Here is my toggle-able content!
My note

Creates:

Toggling content by adding classes
----------------------------------
.. admonition:: Here's my title
:class: dropdown, warning

You can also make elements toggle-able by adding the ``toggle`` class to
them. This can be done with admonitions and containers with the
``:class: my, classes`` keyword.
My custom admonition!

For example, this code would create a toggle-able "note" admonition:
To show the content by default, add a ``toggle-shown`` class as well.

.. code-block:: rst

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

This is my note.

Here's how it looks:
This will generate the following block:

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

This is my note.

Clicking on the toggle button will toggle the item's visibility.
.. _toggle-directive:

Toggle any content with the toggle directive
--------------------------------------------

To show the content by default, add a ``toggle-shown`` class as well.
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:

.. code-block:: rst

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

This is my note.
Here is my toggle-able content!

This will generate the following block:
The code above results in:

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

This is my note.
Here is my toggle-able content!

Here's how they look right after one another:
To show the toggle-able content by default, use the ``:show:`` flag.

.. note::
:class: toggle
.. code-block:: rst

This is my note.
.. toggle::
:show:

.. note::
:class: toggle
Here is my toggle-able content!

This is my second.
It results in the following:

.. toggle::
:show:

Here is my toggle-able content!


Configuration
Expand All @@ -170,42 +169,38 @@ Configuration
Below are a few configuration points for ``sphinx-togglebutton``.


Control the selector text used to make elements toggle-able
-----------------------------------------------------------
Control the togglebutton hover text
-----------------------------------

By default, ``sphinx-togglebutton`` selects any items that have the class ``.toggle``
and adds a toggle-button to them. If you'd like to change this class, for example to
select a different kind of HTML element, you may configure this field manually like so
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:

.. code-block:: python

togglebutton_selector = "your-selector"
togglebutton_hint = "My text"

For example, if you wanted to add toggle-buttons to all HTML elements that had a
``toggle-this-item`` class, in *addition* to the default class of ``toggle``,
you could do so with the following configuration:
Reference
=========

.. code-block:: python
This is a simple reference section to double-check styling etc.

togglebutton_selector = ".toggle, .toggle-this-item"
Here's how they look right after one another:

.. note::
:class: toggle

This is what has been done for the toggle-able section below:
This is my note.

.. note::
:class: toggle-this-item

A toggled note with a custom class to trigger toggling.
:class: toggle

This is my second.

Control the togglebutton hover text
-----------------------------------
.. toggle::

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:
This is my first.

.. code-block:: python
.. toggle::

togglebutton_hint = "My text"
This is my second.
14 changes: 3 additions & 11 deletions sphinx_togglebutton/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,16 +39,8 @@ def run(self):
if "show" in self.options:
classes.append("toggle-shown")

if len(self.arguments) == 0:
parent = nodes.container(classes=classes)
self.state.nested_parse(self.content, self.content_offset, parent)
else:
parent = nodes.admonition(classes=["toggle-body"])
title = nodes.title(self.arguments[0], self.arguments[0])
body = nodes.container(classes=classes)
self.state.nested_parse(self.content, self.content_offset, body)
parent += title
parent += body
parent = nodes.container(classes=classes)
self.state.nested_parse(self.content, self.content_offset, parent)
return [parent]


Expand All @@ -62,7 +54,7 @@ def setup(app):

# Add the string we'll use to select items in the JS
# Tell Sphinx about this configuration variable
app.add_config_value("togglebutton_selector", ".toggle", "html")
app.add_config_value("togglebutton_selector", ".toggle, .admonition.dropdown", "html")
app.add_config_value("togglebutton_hint", "Click to show", "html")
app.add_js_file("togglebutton.js")

Expand Down
Loading