diff --git a/docs/conf.py b/docs/conf.py
index cec7ada..00af8a6 100644
--- a/docs/conf.py
+++ b/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,
diff --git a/docs/index.rst b/docs/index.rst
index c004163..6e65442 100644
--- a/docs/index.rst
+++ b/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 `_. 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.
diff --git a/sphinx_togglebutton/__init__.py b/sphinx_togglebutton/__init__.py
index b1097d8..e883b8d 100644
--- a/sphinx_togglebutton/__init__.py
+++ b/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")
diff --git a/sphinx_togglebutton/_static/togglebutton.css_t b/sphinx_togglebutton/_static/togglebutton.css_t
index d6fe493..c5d3db3 100644
--- a/sphinx_togglebutton/_static/togglebutton.css_t
+++ b/sphinx_togglebutton/_static/togglebutton.css_t
@@ -1,59 +1,62 @@
/* Visibility of the target */
-.toggle {
- transition: opacity .5s;
+.toggle, div.admonition.toggle .admonition-title ~ * {
+ transition: opacity .5s, height .5s;
}
-.toggle-hidden {
+.toggle-hidden:not(.admonition) {
visibility: hidden;
opacity: 0;
height: 1.5em;
- margin: 0px !important;
- padding: 0px !important;
+ margin: 0px;
+ padding: 0px;
+}
+
+/* Overrides for admonition toggles */
+div.admonition.toggle-hidden {
+ height: 3em;
+}
+
+div.admonition.toggle-hidden .admonition-title ~ * {
+ opacity: 0;
+ visibility: hidden;
}
/* Toggle buttons inside admonitions so we see the title */
-.toggle-body {
+.toggle.admonition {
position: relative;
}
-.toggle-body .admonition-title:after {
+.toggle.admonition.admonition-title:after {
content: "" !important;
}
-.toggle-body button.toggle-button {
+/* Note, we'll over-ride this in sphinx-book-theme */
+.toggle.admonition button.toggle-button {
margin-right: 0.5em;
right: 0em;
position: absolute;
- top: .3em;
-}
-
-/* These should be totally hidden since they're inside an admonition */
-
-.toggle-body .toggle-hidden * {
- margin: 0em;
- padding: 0em;
+ top: .2em;
}
-
/* General button style */
button.toggle-button {
background: #999;
border: none;
z-index: 999;
- font-size: 0.7em;
right: -2.5em;
margin-left: -2.5em; /* A hack to keep code blocks from being pushed left */
position: relative;
float: right;
border-radius: 100%;
- width: 23px;
- height: 23px;
+ width: 1.5em;
+ height: 1.5em;
padding: 0px;
}
button.toggle-button.toggle-button-hidden:before {
content: "{{ togglebutton_hint }}";
position: absolute;
+ font-size: .8em;
left: -6.5em;
bottom: .4em;
}
diff --git a/sphinx_togglebutton/_static/togglebutton.js b/sphinx_togglebutton/_static/togglebutton.js
index 894ef8a..3df23e4 100644
--- a/sphinx_togglebutton/_static/togglebutton.js
+++ b/sphinx_togglebutton/_static/togglebutton.js
@@ -1,17 +1,29 @@
var initToggleItems = () => {
var itemsToToggle = document.querySelectorAll(togglebuttonSelector);
-
+ console.log(itemsToToggle, togglebuttonSelector)
// Add the button to each admonition and hook up a callback to toggle visibility
itemsToToggle.forEach((item, index) => {
var toggleID = `toggle-${index}`;
var buttonID = `button-${toggleID}`;
- item.setAttribute('id', toggleID);
var collapseButton = `
`;
- item.insertAdjacentHTML('beforebegin', collapseButton);
+
+ item.setAttribute('id', toggleID);
+
+ if (!item.classList.contains("toggle")){
+ item.classList.add("toggle");
+ }
+
+ // If it's an admonition block, then we'll add the button inside
+ if (item.classList.contains("admonition")) {
+ item.insertAdjacentHTML("afterbegin", collapseButton);
+ } else {
+ item.insertAdjacentHTML('beforebegin', collapseButton);
+ }
+
thisButton = $(`#${buttonID}`);
thisButton.on('click', toggleClickHandler);
if (!item.classList.contains("toggle-shown")) {