ENH: Enhance toggle button design and layout (#32)

Author: choldgraf

docs/conf.py

@@ -74,8 +74,9 @@
 # a list of builtin themes.
 #
 html_theme = "sphinx_book_theme"
-# html_theme = "sphinx_rtd_theme"
+# html_theme = "sphinx_rtd_theme"  # These are just for testing
 # html_theme = "alabaster"
+# html_theme = "furo"
 
 html_theme_options = {
     "repository_url": "https://github.com/executablebooks/sphinx-togglebutton",
@@ -102,7 +103,6 @@
 #
 # html_sidebars = {}
 
-
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.

docs/index.md

@@ -1,48 +1,58 @@
 # `sphinx-togglebutton`
 
 A small sphinx extension to add "toggle button" elements to sections of your page.
-This allows you to:
+For example:
 
-- Collapse admonitions (notes, warnings, etc) so that their content is hidden
-  until users click a toggle button. See {ref}`dropdown-admonitions`.
-- Collapse arbitrary chunks of content on your page with a `toggle` directive.
-  See {ref}`toggle-directive`.
+## Collapse admonitions
 
-:::{admonition} For example, click the "+" button to the right:
+You can collapse admonitions (notes, warnings, etc) so that their content is hidden until users click the admonition title.
+
+:::{admonition} Example: click this title to toggle the content
+:class: dropdown
+You can toggle any admonition to hide its content behind a user click!
+Do so by adding a `dropdown` class to the admonition, like this:
+
+````
+```{note}
 :class: dropdown
 
-Here's a toggled note! You can put all kinds of stuff in here!
+Some content
+```
+````
 :::
 
-You can also add a toggle button to arbitrary chunks of content.
-For example, click the toggle button to the right just below.
+See {ref}`dropdown-admonitions` for more information.
+
+## Hide any content behind a toggle button
+
+You can also hide arbitrary content behind a toggle button.
+When users press the button, they will see the content.
+For example:
 
 ::::{toggle}
-:::{admonition} Wow!
-:class: tip
 
-It's a code block!
+This is a toggled content block!
+It was added like this:
 
-```python
-a = "wow, very python"
+````
+```{toggle}
+This is a toggled content block!
 ```
-:::
+````
+
 ::::
 
-See {ref}`usage` for more information.
+You can either do this with a `{toggle}` directive, or by adding a `toggle` CSS class to any elements you'd like hidden behind a toggle button.
 
-:::{admonition} Check out sphinx-panels as well!
+See [](use:css-selector) for more details.
+
+:::{admonition} Check out sphinx-design as well!
 :class: tip
 
 For a bootstrap-based "dropdown" directive that uses pure CSS, check out
-[Sphinx Panels](https://sphinx-panels.readthedocs.io/en/latest/#dropdown-usage)
+[Sphinx Design](https://sphinx-design.readthedocs.io/en/latest/dropdowns.html)
 :::
 
-```{toctree}
-use
-reference
-```
-
 ## Installation
 
 You can install `sphinx-togglebutton` with `pip`:
@@ -65,3 +75,10 @@ extensions = [
 ```
 
 See {ref}`usage` for information about how to use `sphinx-togglebutton`.
+
+
+```{toctree}
+:maxdepth: 2
+use
+reference/index
+```

docs/reference.md renamed to docs/reference/index.md

@@ -3,126 +3,98 @@
 
 This page covers how to use and configure / customize `sphinx-togglebutton`.
 
-There are two main ways to use `sphinx-togglebutton`:
+There are three main ways to use `sphinx-togglebutton`:
 
+- Wrap arbitrary objects in a toggle button via a CSS selector
 - Collapse admonitions with the `dropdown` class
 - Make arbitrary chunks of content "toggle-able" with the `toggle` directive
 
-Both are described below
+Each is described below
 
-(dropdown-admonitions)=
-## Collapse admonitions with the `dropdown` class
-
-Making dropdown admonitions allows you to insert extra information in your document
-without forcing the user to see that content. For example:
-
-:::{admonition} What could be inside this warning?
-:class: warning, dropdown
+(use:css-selector)=
+## Collapse a block of content with a CSS selector
 
-A whale of a joke!
+You can hide any content and display a toggle button to show it by using certain CSS classes.
+`sphinx-togglebutton` will wrap elements with these classes in a `<details>` block like so:
 
-```{image} https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif
+```html
+<details>
+  <summary>Click to show</summary>
+  <!-- Element that had a CSS class selector -->
+</details>
 ```
-:::
-
-Create a dropdown admonition by adding the `dropdown` class to an admonition directive.
-For example, like so:
-
-::::{tab-set}
 
-:::{tab-item} MyST
+:::{admonition} example
+:class: tip
+This MyST Markdown:
 
 ````md
-
-```{note}
-:class: dropdown
-
-My note
+```{image} https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif
+:class: toggle
 ```
 ````
-
-:::
-
-:::{tab-item} reStructuredText
-
-```rst
-.. note::
-   :class: dropdown
-
-   My note
+results in:
+```{image} https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif
+:class: toggle
 ```
-
 :::
-::::
-
-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:
-
-::::{tab-set}
 
-:::{tab-item} MyST
+### Configure the CSS selector used to insert toggle buttons
 
-````md
-```{admonition} Here's my title
-:class: dropdown, warning
+By default, `sphinx-togglebutton` will use this selector:
 
-My note
 ```
-````
-
-:::
-
-:::{tab-item} reStructuredText
-
-```rst
-.. admonition:: Here's my title
-   :class: dropdown, warning
-
-   My note
+.toggle, .admonition.dropdown
 ```
 
-:::
-::::
-
-Creates:
+However, you can customize this behavior with the `togglebutton_selector` configuration value.
+To specify the selector to use, pass a valid CSS selector as a string:
 
-:::{admonition} Here's my title
-:class: dropdown, warning
+:::{admonition} example
+:class: tip
+Configure `sphinx-togglebutton` to look for a `.toggle-this-element` class and an element with ID `#my-special-id` **instead of** `.toggle` and `.admonition.dropdown`.
 
-My custom admonition!
+```python
+sphinx_togglebutton_selector = ".toggle-this-element, #my-special-id"
+```
 :::
 
-To show the content by default, add a `toggle-shown` class as well.
-
-:::{tab-set-code}
+(dropdown-admonitions)=
+## Collapse admonitions with the `dropdown` class
 
-````markdown
-```{note}
-:class: dropdown, toggle-shown
+`sphinx-togglebutton` treats admonitions as a special case if they are selected.
+If a Sphinx admonition matches the toggle button selector, then its title will be displayed with a button to reveal its content.
 
-This is my note.
+:::{admonition} example
+:class: tip
+````md
+```{admonition} This will be shown
+:class: dropdown
+And this will be hidden!
 ```
 ````
-
-```rst
-.. note::
-    :class: dropdown, toggle-shown
-
-    This is my note.
+results in 
+```{admonition} This will be shown
+:class: dropdown
+And this will be hidden!
 ```
-
 :::
 
-This will generate the following block:
+This works for any kind of Sphinx admoniton:
 
 :::{note}
-:class: dropdown, toggle-shown
+:class: dropdown
+A note!
+:::
 
-This is my note.
+:::{warning}
+:class: dropdown
+A warning!
 :::
 
+
 (toggle-directive)=
-## Toggle any content with the toggle directive
+## Use the `{toggle}` directive to toggle blocks of content
 
 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:
@@ -169,12 +141,37 @@ It results in the following:
 Here is my toggle-able content!
 :::
 
-## Control the togglebutton hover text
+## Change the button hint 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:
+You can control the "hint" text that is displayed next to togglebuttons.
+To do so, use the following configuration variable in your `conf.py` file:
 
 ```python
-togglebutton_hint = "My text"
+togglebutton_hint = "Displayed when the toggle is closed."
+togglebutton_hint_hide = "Displayed when the toggle is open."
+```
+
+## Change the toggle icon color
+
+You can apply some extra styles to the toggle button to achieve the look you want.
+This is particularly useful if the color of the toggle button does not contrast with the background of an admonition.
+
+To style the toggle button, [add a custom CSS file to your documentation](https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html) and include a custom CSS selector like so:
+
+```scss
+// Turn the color red...
+// ...with admonition toggle buttons
+button.toggle-button {
+  color: red;
+}
+
+// ...with content block toggle buttons
+.toggle-button summary {
+  color: red;
+}
 ```
+
+## Printing behavior with toggle buttons
+
+When you print the screen while using `sphinx-togglebutton`, the toggle-able content will not show up.
+To reveal it for printing, you must manually un-toggle the items and then print.

docs/use.md

@@ -24,7 +24,7 @@
     license="MIT License",
     packages=find_packages(),
     package_data={
-        "sphinx_togglebutton": ["_static/togglebutton.css_t", "_static/togglebutton.js"]
+        "sphinx_togglebutton": ["_static/togglebutton.css", "_static/togglebutton.js", "_static/togglebutton-chevron.svg"]
     },
     install_requires=["setuptools", "wheel", "sphinx", "docutils"],
     extras_require={"sphinx": ["matplotlib", "myst_nb", "sphinx_book_theme", "sphinx_design"]},

setup.py

@@ -11,9 +11,11 @@ def st_static_path(app):
     app.config.html_static_path.append(static_path)
 
 
-def add_to_context(app, config):
+def initialize_js_assets(app, config):
     # Update the global context
-    config.html_context.update({"togglebutton_hint": config.togglebutton_hint})
+    app.add_js_file(None, body=f"let toggleHintShow = '{config.togglebutton_hint}';")
+    app.add_js_file(None, body=f"let toggleHintHide = '{config.togglebutton_hint_hide}';")
+    app.add_js_file("togglebutton.js")
 
 
 # This function reads in a variable and inserts it into JavaScript
@@ -56,11 +58,11 @@ def setup(app):
     # Tell Sphinx about this configuration variable
     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")
+    app.add_config_value("togglebutton_hint_hide", "Click to hide", "html")
 
     # Run the function after the builder is initialized
     app.connect("builder-inited", insert_custom_selection_config)
-    app.connect("config-inited", add_to_context)
+    app.connect("config-inited", initialize_js_assets)
     app.add_directive("toggle", Toggle)
     return {
         "version": __version__,