adding toggle directive

Author: choldgraf

docs/conf.py

@@ -38,9 +38,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx_togglebutton"]
+extensions = ["myst_nb", "sphinx_togglebutton"]
 
-togglebutton_selector = ".toggle, .secondtoggle"
+# togglebutton_selector = ".toggle, .secondtoggle"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/index.rst

@@ -7,23 +7,26 @@ sections of your page.
 
 For example, click the "+" button to the right:
 
-.. note:: Here's a toggled admonition
-    :class: toggle
+.. toggle::
+
+    .. note:: Here's a toggled admonition
 
 It was created with this code:
 
-.. code:: rst
+.. code-block:: rst
 
-    .. note:: Here's a toggled admonition
-        :class: toggle
+    .. toggle::
+
+        .. note:: Here's a toggled admonition
 
-        (admonition body here)
+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:
 
-And here's a code block:
+.. toggle:: Toggle to see what's inside
 
-.. container:: toggle
+    It's a code block!
 
-    .. code:: python
+    .. code-block:: python
 
         a = "wow, very python"
         print("this code should be toggle-able!")
@@ -34,7 +37,7 @@ Installation
 
 You can install `sphinx-togglebutton` with `pip`:
 
-.. code:: bash
+.. code-block:: bash
 
     pip install sphinx-togglebutton
 
@@ -47,113 +50,115 @@ to your extensions list.
 
 E.g.:
 
-.. code:: python
+.. code-block:: python
 
     extensions = [
         ...
         'sphinx_togglebutton'
         ...
     ]
 
-Now, whenever you wish for an admonition to be toggle-able, add the
-``:class: toggle`` parameter to the admonition directive that you use.
 
-For example, this code would create a toggle-able "note" admonition:
+The toggle directive
+--------------------
 
-.. code:: rst
+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:
 
-    .. note::
-        :class: toggle
+.. code-block:: rst
 
-        This is my note.
+    .. toggle::
 
-Here's how it looks:
+        Here is my toggle-able content!
 
-.. note::
-    :class: toggle
+The code above results in:
 
-    This is my note.
+.. toggle::
 
-Clicking on the toggle button will toggle the item's visibility.
+    Here is my toggle-able content!
 
+You can also add titles to your toggle-able content:
 
-Show content by default
------------------------
+.. code-block:: rst
 
-By default, all items with toggle buttons added to them will be hidden by
-default. You may also **show the content by default**. To do so, add the
-``toggle`` class *as well as* a ``toggle-shown`` class, like so:
+    .. toggle:: My title
 
-.. code:: rst
+        Here is my toggle-able content!
 
-    .. note::
-        :class: toggle, toggle-shown
+Which results in:
 
-        This is my note.
 
-This will generate the following block:
+.. toggle:: My title
 
-.. note::
-    :class: toggle, toggle-shown
+    Here is my toggle-able content!
 
-    This is my note.
+To show the toggle-able content by default, use the ``:show:`` flag.
 
-Toggle any container of content
--------------------------------
+.. code-block:: rst
 
-You can also use **containers** to add arbitrary toggle-able code. For example,
-here's a container with an image inside:
+    .. toggle::
+        :show:
 
-.. container:: toggle
+        Here is my toggle-able content!
 
-    .. admonition:: Look at that, an image!
+It results in the following:
 
-        .. image:: https://media.giphy.com/media/mW05nwEyXLP0Y/giphy.gif
+.. toggle::
+    :show:
 
-It was generated with this code:
+    Here is my toggle-able content!
 
-.. code:: rst
 
-    .. container:: toggle
+Toggling content by adding classes
+----------------------------------
 
-        .. admonition:: Look at that, an image!
+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.
 
-            .. image:: https://media.giphy.com/media/mW05nwEyXLP0Y/giphy.gif
+For example, this code would create a toggle-able "note" admonition:
 
-Here's how they look right after one another:
+.. code-block:: rst
+
+    .. note::
+        :class: toggle
+
+        This is my note.
+
+Here's how it looks:
 
 .. note::
     :class: toggle
 
     This is my note.
 
-.. note::
-    :class: toggle
+Clicking on the toggle button will toggle the item's visibility.
 
-    This is my second.
 
-Customize the selector words used to toggle content
----------------------------------------------------
+To show the content by default, add a ``toggle-shown`` class as well.
 
-``sphinx-togglebutton`` adds a toggle button to elements that are selected
-by a CSS selection query. By default, this is ``.toggle``. You can customize
-the query that is used with the following Sphinx parameter (in ``conf.py``):
+.. code-block:: rst
 
-.. code-block:: python
+    .. note::
+        :class: toggle, toggle-shown
+
+        This is my note.
 
-    togglebutton_selector = "<your-selector>
+This will generate the following block:
 
-For example, the documentation with this site uses the following configuration
-value:
+.. note::
+    :class: toggle, toggle-shown
 
-.. code-block:: python
+    This is my note.
 
-    togglebutton_selector = ".toggle, .secondtoggle"
+Here's how they look right after one another:
 
-This means that any element with either of these classes will have toggle
-buttons added to them.
+.. note::
+    :class: toggle
+
+    This is my note.
 
 .. note::
-    :class: secondtoggle
+    :class: toggle
 
-    A note with a ``.secondtoggle`` class.
+    This is my second.

setup.py

@@ -21,6 +21,6 @@
         "sphinx_togglebutton": ["_static/togglebutton.css", "_static/togglebutton.js"]
     },
     install_requires=["setuptools", "wheel", "sphinx"],
-    extras_require={"sphinx": ["sphinx"]},
+    extras_require={"sphinx": ["sphinx", "myst_nb"]},
     classifiers=["License :: OSI Approved :: MIT License"],
 )

sphinx_togglebutton/__init__.py

@@ -1,5 +1,8 @@
 """A small sphinx extension to add "toggle" buttons to items."""
 import os
+import sphinx
+from docutils.parsers.rst import Directive, directives
+from docutils import nodes
 
 __version__ = "0.0.3dev0"
 
@@ -17,6 +20,34 @@ def insert_custom_selection_config(app):
     app.add_js_file(None, body=js_text)
 
 
+class Toggle(Directive):
+    """Hide a block of markup text by wrapping it in a container."""
+
+    optional_arguments = 1
+    final_argument_whitespace = True
+    has_content = True
+
+    option_spec = {"id": directives.unchanged, "show": directives.flag}
+
+    def run(self):
+        self.assert_has_content()
+        classes = ["toggle"]
+        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
+        return [parent]
+
+
 # We connect this function to the step after the builder is initialized
 def setup(app):
     # Add our static path
@@ -32,7 +63,7 @@ def setup(app):
 
     # Run the function after the builder is initialized
     app.connect("builder-inited", insert_custom_selection_config)
-
+    app.add_directive("toggle", Toggle)
     return {
         "version": __version__,
         "parallel_read_safe": True,

sphinx_togglebutton/_static/togglebutton.css

@@ -1,12 +1,33 @@
 /* Visibility of the target */
-div.toggle-hidden {
+.toggle {
+    transition: opacity .5s;
+}
+
+.toggle-hidden {
     visibility: hidden;
     opacity: 0;
     height: 1.5em;
     margin: 0px !important;
     padding: 0px !important;
 }
 
+.toggle-body .admonition-title:after {
+    content: "";
+}
+
+.toggle-body button.toggle-button {
+    margin-right: 0.5em;
+    right: 0em;
+}
+
+/* These should be totally hidden since they're inside an admonition */
+
+.toggle-body .toggle-hidden * {
+    margin: 0em;
+    padding: 0em;
+}
+
+
 /* General button style */
 button.toggle-button {
     background: #999;

sphinx_togglebutton/_static/togglebutton.js

@@ -24,6 +24,7 @@ var initToggleItems = () => {
 var toggleHidden = (button) => {
   target = button.dataset['target']
   var itemToToggle = document.getElementById(target);
+  console.log(itemToToggle)
   if (itemToToggle.classList.contains("toggle-hidden")) {
     itemToToggle.classList.remove("toggle-hidden");
     button.classList.remove("toggle-button-hidden");