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")) {