diff --git a/docs/conf.py b/docs/conf.py index ce4c3af..967814f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,7 +38,7 @@ # 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_design", "sphinx_togglebutton"] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -78,13 +78,15 @@ # html_theme = "alabaster" html_theme_options = { - "single_page": True, "repository_url": "https://github.com/executablebooks/sphinx-togglebutton", "use_repository_button": True, "use_issues_button": True, "use_edit_page_button": True, + "home_page_in_toc": True, } +myst_enable_extensions = ["colon_fence"] + # 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, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..a622a3c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,67 @@ +# `sphinx-togglebutton` + +A small sphinx extension to add "toggle button" elements to sections of your page. +This allows you to: + +- 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`. + +:::{admonition} For example, click the "+" button to the right: +:class: dropdown + +Here's a toggled note! You can put all kinds of stuff in here! +::: + +You can also add a toggle button to arbitrary chunks of content. +For example, click the toggle button to the right just below. + +::::{toggle} +:::{admonition} Wow! +:class: tip + +It's a code block! + +```python +a = "wow, very python" +``` +::: +:::: + +See {ref}`usage` for more information. + +:::{admonition} Check out sphinx-panels 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) +::: + +```{toctree} +use +reference +``` + +## Installation + +You can install `sphinx-togglebutton` with `pip`: + +```bash +pip install sphinx-togglebutton +``` + +Then, activate it in your `sphinx` build by adding it to your `conf.py` configuration +file, like so: + +E.g.: + +```python +extensions = [ + ... + 'sphinx_togglebutton' + ... +] +``` + +See {ref}`usage` for information about how to use `sphinx-togglebutton`. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 87187fd..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,233 +0,0 @@ -=================== -sphinx-togglebutton -=================== - -A small sphinx extension to make it possible to add a "toggle button" to -sections of your page. This allows you to: - -- 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`. - - -.. admonition:: For example, click the "+" button to the right: - :class: dropdown - - Here's a toggled note! You can put all kinds of stuff in here! - -You can also add a toggle button to arbitrary chunks of content. -For example, click the toggle button to the right just below. - -.. toggle:: - - .. admonition:: Wow! - :class: tip - - It's a code block! - - .. code-block:: python - - a = "wow, very python" - -See :ref:`usage` for more information. - - -.. admonition:: Check out sphinx-panels as well! - :class: tip - - For a bootstrap-based "dropdown" directive that uses pure CSS, check out - `Sphinx Panels `_ - - -Installation -============ - -You can install `sphinx-togglebutton` with `pip`: - -.. code-block:: bash - - pip install sphinx-togglebutton - -Then, activate it in your ``sphinx`` build by adding it to your ``conf.py`` configuration -file, like so: - -E.g.: - -.. code-block:: python - - extensions = [ - ... - 'sphinx_togglebutton' - ... - ] - -See :ref:`usage` for information about how to use ``sphinx-togglebutton``. - -.. _usage: - -Usage -===== - -There are two main ways to use ``sphinx-togglebutton``: - -- Collapse admonitions with the ``dropdown`` class -- Make arbitrary chunks of content "toggle-able" with the ``toggle::`` directive - -.. 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! - -.. _dropdown-admonitions: - -Dropdown admonitions by adding classes --------------------------------------- - -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 - - A whale of a joke! - - .. image:: https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif - - (sorry) - -Create a dropdown admonition by adding the ``dropdown`` class to an admonition directive. -For example, like so: - -.. code-block:: rst - - .. note:: - :class: dropdown - - My note - -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 - - .. admonition:: Here's my title - :class: dropdown, warning - - My note - -Creates: - -.. admonition:: Here's my title - :class: dropdown, warning - - My custom admonition! - -To show the content by default, add a ``toggle-shown`` class as well. - -.. code-block:: rst - - .. note:: - :class: dropdown, toggle-shown - - This is my note. - -This will generate the following block: - -.. note:: - :class: dropdown, toggle-shown - - This is my note. - -.. _toggle-directive: - -Toggle any content with the toggle directive --------------------------------------------- - -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 - - .. toggle:: - - Here is my toggle-able content! - -The code above results in: - -.. toggle:: - - Here is my toggle-able content! - -To show the toggle-able content by default, use the ``:show:`` flag. - -.. code-block:: rst - - .. toggle:: - :show: - - Here is my toggle-able content! - -It results in the following: - -.. toggle:: - :show: - - Here is my toggle-able content! - - -Configuration -============= - -Below are a few configuration points for ``sphinx-togglebutton``. - - -Control the togglebutton hover 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: - -.. code-block:: python - - togglebutton_hint = "My text" - -Reference -========= - -This is a simple reference section to double-check styling etc. - -Here's how they look right after one another: - -.. note:: - :class: toggle - - This is my note. - -.. note:: - :class: toggle - - This is my second. - -.. toggle:: - - This is my first. - -.. toggle:: - - This is my second. - -.. admonition:: A really long admonition that will take up multiple lines A really long admonition that will take up multiple lines - :class: toggle - - Admonition content. - - .. image:: https://jupyterbook.org/_static/logo.png - -.. admonition:: A really long admonition that will take up multiple lines A really long admonition that will take up multiple lines - - Admonition content. - - .. image:: https://jupyterbook.org/_static/logo.png \ No newline at end of file diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 0000000..605346f --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,112 @@ +--- +jupytext: + formats: md:myst + text_representation: + extension: .md + format_name: myst + format_version: 0.13 + jupytext_version: 1.11.5 +kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 +--- + +# Reference examples + +This page shows the most common ways that `sphinx-togglebutton` is used as a reference. +This is a benchmark for styling, and also helps demonstrate the behavior of this extension. + +## Use amongst text + +Here's a paragraph, it's just here to provide some text context for the togglebuttons in this section. + +:::{note} +:class: toggle + +A test toggle admonition. +::: + +Here's a paragraph, it's just here to provide some text context for the togglebuttons in this section. + +:::{toggle} +A test toggle directive. +::: + + +Here's a paragraph, it's just here to provide some text context for the togglebuttons in this section. + + +## Sequential toggle buttons + +Here's how they look right after one another: + +### Admonition toggles + +:::{note} +:class: toggle + +This is my note. +::: + +:::{note} +:class: toggle + +This is my second. +::: + +### Toggle directive + +:::{toggle} +This is my first. +::: + +:::{toggle} +This is my second. +::: + +## Long titles + +:::{admonition} A really long admonition that will take up multiple lines A really long admonition that will take up multiple lines +:class: toggle + +Admonition content. + +```{image} https://jupyterbook.org/_static/logo-wide.svg +``` +::: + +## MyST-NB Cells + +```{code-cell} +from matplotlib import pyplot as plt +import numpy as np +data = np.random.randn(3, 100) +``` + +### Hide Input + +```{code-cell} +:tags: [hide-input] + +fig, ax = plt.subplots() +ax.scatter(data[0], data[1], c=np.abs(data[2])) +``` + +### Hide Output + +```{code-cell} +:tags: [hide-output] + +fig, ax = plt.subplots() +ax.scatter(data[0], data[1], c=np.abs(data[2])) +``` + +### Hide Both + +```{code-cell} +:tags: [hide-cell] + +fig, ax = plt.subplots() +ax.scatter(data[0], data[1], c=np.abs(data[2])) +``` diff --git a/docs/use.md b/docs/use.md new file mode 100644 index 0000000..baa9d55 --- /dev/null +++ b/docs/use.md @@ -0,0 +1,180 @@ +(usage)= +# Use and configure + +This page covers how to use and configure / customize `sphinx-togglebutton`. + +There are two main ways to use `sphinx-togglebutton`: + +- Collapse admonitions with the `dropdown` class +- Make arbitrary chunks of content "toggle-able" with the `toggle` directive + +Both are 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 + +A whale of a joke! + +```{image} https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif +``` +::: + +Create a dropdown admonition by adding the `dropdown` class to an admonition directive. +For example, like so: + +::::{tab-set} + +:::{tab-item} MyST + +````md + +```{note} +:class: dropdown + +My note +``` +```` + +::: + +:::{tab-item} reStructuredText + +```rst +.. note:: + :class: dropdown + + My note +``` + +::: +:::: + +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 + +````md +```{admonition} Here's my title +:class: dropdown, warning + +My note +``` +```` + +::: + +:::{tab-item} reStructuredText + +```rst +.. admonition:: Here's my title + :class: dropdown, warning + + My note +``` + +::: +:::: + +Creates: + +:::{admonition} Here's my title +:class: dropdown, warning + +My custom admonition! +::: + +To show the content by default, add a `toggle-shown` class as well. + +:::{tab-set-code} + +````markdown +```{note} +:class: dropdown, toggle-shown + +This is my note. +``` +```` + +```rst +.. note:: + :class: dropdown, toggle-shown + + This is my note. +``` + +::: + +This will generate the following block: + +:::{note} +:class: dropdown, toggle-shown + +This is my note. +::: + +(toggle-directive)= +## Toggle any content with the toggle directive + +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: + +:::{tab-set-code} + +````markdown +```{toggle} +Here is my toggle-able content! +``` +```` + +```rst +.. toggle:: + + Here is my toggle-able content! +``` + +::: + + +The code above results in: + +:::{toggle} + +Here is my toggle-able content! +::: + +To show the toggle-able content by default, use the `:show:` flag. + +````markdown +```{toggle} +:show: + +Here is my toggle-able content! +``` +```` + +It results in the following: + +:::{toggle} +:show: + +Here is my toggle-able content! +::: + +## Control the togglebutton hover 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: + +```python +togglebutton_hint = "My text" +``` diff --git a/setup.py b/setup.py index 41dc9e2..751d10b 100644 --- a/setup.py +++ b/setup.py @@ -27,6 +27,6 @@ "sphinx_togglebutton": ["_static/togglebutton.css_t", "_static/togglebutton.js"] }, install_requires=["setuptools", "wheel", "sphinx", "docutils"], - extras_require={"sphinx": ["myst_nb", "sphinx_book_theme"]}, + extras_require={"sphinx": ["matplotlib", "myst_nb", "sphinx_book_theme", "sphinx_design"]}, classifiers=["License :: OSI Approved :: MIT License"], ) diff --git a/sphinx_togglebutton/_static/togglebutton.js b/sphinx_togglebutton/_static/togglebutton.js index df33bac..41b77f9 100644 --- a/sphinx_togglebutton/_static/togglebutton.js +++ b/sphinx_togglebutton/_static/togglebutton.js @@ -1,40 +1,47 @@ var initToggleItems = () => { var itemsToToggle = document.querySelectorAll(togglebuttonSelector); - console.log(itemsToToggle, togglebuttonSelector) + console.log(`[togglebutton]: Adding toggle buttons to ${itemsToToggle.length} items`) // Add the button to each admonition and hook up a callback to toggle visibility itemsToToggle.forEach((item, index) => { + // Generate unique IDs for this item var toggleID = `toggle-${index}`; var buttonID = `button-${toggleID}`; - var 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 + // This is the button that will be added to each item to trigger the toggle + var collapseButton = ` + `; + + // Add the button HTML to this element and assign it as a variable to use later if (item.classList.contains("admonition")) { + // If it's an admonition block, then we'll add the button inside item.insertAdjacentHTML("afterbegin", collapseButton); } else { item.insertAdjacentHTML('beforebegin', collapseButton); } - thisButton = document.getElementById(buttonID); - thisButton.on('click', toggleClickHandler); + + // Add click handlers for the button + admonition title (if admonition) + thisButton.addEventListener('click', toggleClickHandler); + // If admonition has a single direct-child title make it clickable. admonitionTitle = document.querySelector(`#${toggleID} > .admonition-title`) if (admonitionTitle) { - admonitionTitle.on('click', toggleClickHandler); + admonitionTitle.addEventListener('click', toggleClickHandler); admonitionTitle.dataset.target = toggleID admonitionTitle.dataset.button = buttonID } + + // Now hide the item for this toggle button unless explicitly noted to show if (!item.classList.contains("toggle-shown")) { - toggleHidden(thisButton[0]); + toggleHidden(thisButton); } }) }; diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..c9d307c --- /dev/null +++ b/tox.ini @@ -0,0 +1,29 @@ +# To use tox, see https://tox.readthedocs.io + +[tox] +envlist = py39-sphinx3 + +[testenv] +# only recreate the environment when we use `tox -r` +recreate = false + +[testenv:docs] +description = Build the documentation +extras = + sphinx +commands = + sphinx-build \ + -n -b {posargs:html} docs/ docs/_build/{posargs:html} + +[testenv:docs-live] +description = Auto-build and preview the documentation in the browser +deps = + sphinx-autobuild +extras = + sphinx +commands = + sphinx-autobuild \ + --re-ignore _build/.* \ + --watch sphinx_togglebutton \ + --port 0 --open-browser \ + -n -b {posargs:html} docs/ docs/_build/{posargs:html}