Merge pull request #13 from executablebooks/toggle_admonition

using classes for admonition toggles

Author: choldgraf

docs/conf.py

@@ -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"]
 
@@ -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,

docs/index.rst

@@ -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
 ============
@@ -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.:
 
@@ -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
@@ -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.

sphinx_togglebutton/__init__.py

@@ -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]
 
 
@@ -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")