👌 IMPROVE: Replace sphinx-togglebutton with built-in functionality (#446

)

This allows for tighter integration with myst-nb:

- Nicer rendering of the hidden content buttons
- Customisation of the hide/show prompts

The implementation uses "static" details/summary HTML tags directly + CSS,
similar to [sphinx-design](https:/executablebooks/sphinx-design),
rather than the JS implementation used by sphinx-togglebutton.

docs/render/hiding.md

@@ -7,8 +7,7 @@ kernelspec:
 # Hide cell contents
 
 You can use Jupyter Notebook **cell tags** to control some of the behavior of
-the rendered notebook. This uses the [**`sphinx-togglebutton`**](https://sphinx-togglebutton.readthedocs.io/en/latest/)
-package to add a little button that toggles the visibility of content.[^download]
+the rendered notebook.[^download]
 
 [^download]: This notebook can be downloaded as
  **{nb-download}`hiding.ipynb`** and {download}`hiding.md`
@@ -66,6 +65,31 @@ fig, ax = plt.subplots()
 points =ax.scatter(*data, c=data[0], s=data[0])
 ```
 
+You can control the hide/show prompts by using the `code_prompt_show` and `code_prompt_hide` configuration options.
+`{type}` will be replaced with `content`, `source`, or `outputs`, depending on the hide tag.
+See the {ref}`config/intro` section for more details.
+
+````markdown
+
+```{code-cell} ipython3
+:tags: [hide-cell]
+:mystnb:
+: code_prompt_show: "My show prompt"
+: code_prompt_hide: "My hide prompt"
+
+print("hallo world")
+```
+````
+
+```{code-cell} ipython3
+:tags: [hide-cell]
+:mystnb:
+: code_prompt_show: "My show prompt for {type}"
+: code_prompt_hide: "My hide prompt for {type}"
+
+print("hallo world")
+```
+
 (use/hiding/markdown)=
 
 ## Hide markdown cells

myst_nb/core/config.py

@@ -323,6 +323,35 @@ def __post_init__(self):
  ),
  },
  )
+
+ code_prompt_show: str = dc.field(
+ default="Show code cell {type}",
+ metadata={
+ "validator": instance_of(str),
+ "help": "Prompt to expand hidden code cell {content|source|outputs}",
+ "sections": (
+ Section.global_lvl,
+ Section.file_lvl,
+ Section.cell_lvl,
+ Section.render,
+ ),
+ },
+ )
+
+ code_prompt_hide: str = dc.field(
+ default="Hide code cell {type}",
+ metadata={
+ "validator": instance_of(str),
+ "help": "Prompt to collapse hidden code cell {content|source|outputs}",
+ "sections": (
+ Section.global_lvl,
+ Section.file_lvl,
+ Section.cell_lvl,
+ Section.render,
+ ),
+ },
+ )
+
  number_source_lines: bool = dc.field(
  default=False,
  metadata={

myst_nb/core/render.py

@@ -128,38 +128,49 @@ def render_nb_cell_raw(self: SelfType, token: SyntaxTreeNode) -> None:
  def render_nb_cell_code(self: SelfType, token: SyntaxTreeNode) -> None:
  """Render a notebook code cell."""
  cell_index = token.meta["index"]
+ cell_line = token_line(token, 0) or None
  tags = token.meta["metadata"].get("tags", [])
 
  exec_count, outputs = self._get_nb_code_cell_outputs(token)
 
+ classes = ["cell"]
+ for tag in tags:
+ classes.append(f"tag_{tag.replace(' ', '_')}")
+
  # TODO do we need this -/_ duplication of tag names, or can we deprecate one?
+ hide_cell = "hide-cell" in tags
  remove_input = (
  self.get_cell_level_config(
- "remove_code_source",
- token.meta["metadata"],
- line=token_line(token, 0) or None,
+ "remove_code_source", token.meta["metadata"], line=cell_line
  )
  or ("remove_input" in tags)
  or ("remove-input" in tags)
  )
+ hide_input = "hide-input" in tags
  remove_output = (
  self.get_cell_level_config(
- "remove_code_outputs",
- token.meta["metadata"],
- line=token_line(token, 0) or None,
+ "remove_code_outputs", token.meta["metadata"], line=cell_line
  )
  or ("remove_output" in tags)
  or ("remove-output" in tags)
  )
+ hide_output = "hide-output" in tags
 
  # if we are remove both the input and output, we can skip the cell
  if remove_input and remove_output:
  return
 
+ hide_mode = None
+ if hide_cell:
+ hide_mode = "all"
+ elif hide_input and hide_output:
+ hide_mode = "all"
+ elif hide_input:
+ hide_mode = "input"
+ elif hide_output:
+ hide_mode = "output"
+
  # create a container for all the input/output
- classes = ["cell"]
- for tag in tags:
- classes.append(f"tag_{tag.replace(' ', '_')}")
  cell_container = nodes.container(
  nb_element="cell_code",
  cell_index=cell_index,
@@ -168,6 +179,17 @@ def render_nb_cell_code(self: SelfType, token: SyntaxTreeNode) -> None:
  cell_metadata=token.meta["metadata"],
  classes=classes,
  )
+ if hide_mode:
+ cell_container["hide_mode"] = hide_mode
+ code_prompt_show = self.get_cell_level_config(
+ "code_prompt_show", token.meta["metadata"], line=cell_line
+ )
+ code_prompt_hide = self.get_cell_level_config(
+ "code_prompt_hide", token.meta["metadata"], line=cell_line
+ )
+ cell_container["prompt_show"] = code_prompt_show
+ cell_container["prompt_hide"] = code_prompt_hide
+
  self.add_line_and_source_path(cell_container, token)
  with self.current_node_context(cell_container, append=True):
 

myst_nb/sphinx_.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 from collections import defaultdict
+from html import escape
 import json
 from pathlib import Path
 import re
@@ -21,6 +22,7 @@
 from sphinx.environment.collectors import EnvironmentCollector
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import logging as sphinx_logging
+from sphinx.util.docutils import SphinxTranslator
 
 from myst_nb._compat import findall
 from myst_nb.core.config import NbParserConfig
@@ -472,3 +474,79 @@ def default(self, obj):
  if isinstance(obj, bytes):
  return obj.decode("ascii")
  return json.JSONEncoder.default(self, obj)
+
+
+class HideCodeCellNode(nodes.Element):
+ """Node for hiding cell input."""
+
+ @classmethod
+ def add_to_app(cls, app: Sphinx):
+ app.add_node(cls, html=(visit_HideCellInput, depart_HideCellInput))
+
+
+def visit_HideCellInput(self: SphinxTranslator, node: HideCodeCellNode):
+ classes = " ".join(node["classes"])
+ self.body.append(f'<details class="hide {classes}">\n')
+ self.body.append('<summary aria-label="Toggle hidden content">\n')
+ self.body.append(f'<span class="collapsed">{escape(node["prompt_show"])}</span>\n')
+ self.body.append(f'<span class="expanded">{escape(node["prompt_hide"])}</span>\n')
+ self.body.append("</summary>\n")
+
+
+def depart_HideCellInput(self: SphinxTranslator, node: HideCodeCellNode):
+ self.body.append("</details>\n")
+
+
+class HideInputCells(SphinxPostTransform):
+ """Hide input cells in the HTML output."""
+
+ default_priority = 199
+ formats = ("html",)
+
+ def run(self, **kwargs):
+
+ for node in findall(self.document)(nodes.container):
+
+ if (
+ node.get("nb_element") == "cell_code"
+ and node.get("hide_mode")
+ and node.children
+ ):
+ hide_mode = node.get("hide_mode")
+ has_input = node.children[0].get("nb_element") == "cell_code_source"
+ has_output = node.children[-1].get("nb_element") == "cell_code_output"
+
+ # if we have the code source (input) element,
+ # and we are collapsing the input or input+output
+ # then we attach the "collapse button" above the input
+ if has_input and hide_mode == "input":
+ wrap_node = HideCodeCellNode(
+ prompt_show=node["prompt_show"].replace("{type}", "source"),
+ prompt_hide=node["prompt_hide"].replace("{type}", "source"),
+ )
+ wrap_node["classes"].append("above-input")
+ code = node.children[0]
+ wrap_node.append(code)
+ node.replace(code, wrap_node)
+
+ elif has_input and hide_mode == "all":
+ wrap_node = HideCodeCellNode(
+ prompt_show=node["prompt_show"].replace("{type}", "content"),
+ prompt_hide=node["prompt_hide"].replace("{type}", "content"),
+ )
+ wrap_node["classes"].append("above-input")
+ wrap_node.extend(node.children)
+ node.children = [wrap_node]
+
+ # if we don't have the code source (input) element,
+ # or are only hiding the output,
+ # then we place the "collapse button" above the output
+ elif has_output and hide_mode in ("output", "all"):
+ wrap_node = HideCodeCellNode(
+ prompt_show=node["prompt_show"].replace("{type}", "outputs"),
+ prompt_hide=node["prompt_hide"].replace("{type}", "outputs"),
+ )
+ wrap_node["classes"].append("above-output")
+ output = node.children[-1]
+ wrap_node.append(output)
+ node.replace(output, wrap_node)

myst_nb/sphinx_ext.py

@@ -19,7 +19,13 @@
 from myst_nb.ext.eval import load_eval_sphinx
 from myst_nb.ext.glue import load_glue_sphinx
 from myst_nb.ext.glue.crossref import ReplacePendingGlueReferences
-from myst_nb.sphinx_ import NbMetadataCollector, Parser, SelectMimeType
+from myst_nb.sphinx_ import (
+ HideCodeCellNode,
+ HideInputCells,
+ NbMetadataCollector,
+ Parser,
+ SelectMimeType,
+)
 
 SPHINX_LOGGER = sphinx_logging.getLogger(__name__)
 OUTPUT_FOLDER = "jupyter_execute"
@@ -83,17 +89,16 @@ def sphinx_setup(app: Sphinx):
  app.add_post_transform(SelectMimeType)
  app.add_post_transform(ReplacePendingGlueReferences)
 
+ # setup collapsible content
+ app.add_post_transform(HideInputCells)
+ HideCodeCellNode.add_to_app(app)
+
  # add HTML resources
  app.add_css_file("mystnb.css")
  app.connect("build-finished", add_global_html_resources)
  # note, this event is only available in Sphinx >= 3.5
  app.connect("html-page-context", add_per_page_html_resources)
 
- # add configuration for hiding cell input/output
- # TODO replace this, or make it optional
- app.setup_extension("sphinx_togglebutton")
- app.connect("config-inited", update_togglebutton_classes)
-
  # Note lexers are registered as `pygments.lexers` entry-points
  # and so do not need to be added here.
 
@@ -191,17 +196,3 @@ def add_per_page_html_resources(
  js_files = NbMetadataCollector.get_js_files(app.env, pagename) # type: ignore
  for path, kwargs in js_files.values():
  app.add_js_file(path, **kwargs) # type: ignore
-
-
-def update_togglebutton_classes(app: Sphinx, config):
- """Update togglebutton classes to recognise hidden cell inputs/outputs."""
- to_add = [
- ".tag_hide_input div.cell_input",
- ".tag_hide-input div.cell_input",
- ".tag_hide_output div.cell_output",
- ".tag_hide-output div.cell_output",
- ".tag_hide_cell.cell",
- ".tag_hide-cell.cell",
- ]
- for selector in to_add:
- config.togglebutton_selector += f", {selector}"

myst_nb/static/mystnb.css

@@ -15,13 +15,70 @@ div.container.cell {
 }
 
 /* Input cells */
-div.cell div.cell_input {
+div.cell div.cell_input,
+div.cell details.above-input > summary {
  padding-left: 0em;
  padding-right: 0em;
  border: 1px #ccc solid;
  background-color: #f7f7f7;
  border-left-color: green;
  border-left-width: medium;
+ border-radius: .4em;
+}
+
+div.cell details.above-input div.cell_input {
+ border-top-left-radius: 0;
+ border-top-right-radius: 0;
+ border-top: 1px #ccc dashed;
+}
+
+div.cell details.above-input > summary {
+ border-bottom-left-radius: 0;
+ border-bottom-right-radius: 0;
+ border-bottom: 1px #ccc dashed;
+ padding-left: 1em;
+ margin-bottom: 0;
+}
+
+div.cell details.above-output > summary {
+ background-color: #f7f7f7;
+ padding-left: 1em;
+ padding-right: 0em;
+ border: 1px #ccc solid;
+ border-bottom: 1px #ccc dashed;
+ border-left-color: blue;
+ border-left-width: medium;
+ border-top-left-radius: .4em;
+ border-top-right-radius: .4em;
+}
+
+div.cell details.hide > summary::marker {
+ opacity: 50%;
+}
+
+div.cell details.hide > summary > span {
+ opacity: 50%;
+}
+
+div.cell details.hide[open] > summary > span.collapsed {
+ display: none;
+}
+div.cell details.hide:not([open]) > summary > span.expanded {
+ display: none;
+}
+
+@keyframes collapsed-fade-in {
+ 0% {
+ opacity: 0;
+ }
+ 100% {
+ opacity: 1;
+ }
+}
+div.cell details.hide[open] > summary ~ * {
+ -moz-animation: collapsed-fade-in 0.3s ease-in-out;
+ -webkit-animation: collapsed-fade-in 0.3s ease-in-out;
+ animation: collapsed-fade-in 0.3s ease-in-out;
 }
 
 div.cell_input > div, div.cell_output div.output > div.highlight {