search

jupyterlite / jupyterlite-sphinx

Sphinx extension using JupyterLite to render Notebooks
https://jupyterlite-sphinx.readthedocs.io/en/latest
BSD 3-Clause "New" or "Revised" License
68 stars 21 forks source link

Make an option to collapse an embedded iframe #70

Open jasongrout opened 2 years ago

jasongrout commented 2 years ago

Problem

An embedded retrolite or jlab iframe is really valuable to have in a docs page as it provides the user an immediate opportunity to interact, but it comes with a heavy download cost that projects may not want to pay, particularly on their front docs page. However, providing only a link to a separate retrolite page may stifle user engagement too much by requiring an extra click and navigation away from the current page.

Proposed Solution

Provide an option for embedded iframes to be initially collapsed with an HTML details element, like this:

<details><summary>Try it now!</summary>[embedded iframe]</details>
Try it now![embedded iframe]

We could even lazily create the iframe with a bit of javascript that listens for the details toggle event, so the initial page load doesn't automatically trigger a heavy download of retrolite.

Additional context

This came up in a discussion in ipyleaflet about whether we should have an embedded retrolite on the front page of the docs (see https://github.com/jupyter-widgets/ipyleaflet/pull/1007#event-7126510079). The idea of using a details element was suggested by @williamstein when we were discussing putting an embedded retrolite on the front page of the ipywidgets documentation.

jasongrout commented 2 years ago

Ah, I see lazy loading was introduced in https://github.com/jupyterlite/jupyterlite-sphinx/pull/67 in a very nice way! So this issue is more about providing a way to not take up the vertical space for an inactive retrolite.

martinRenou commented 2 years ago

Thank you for the suggestion!

Maybe this could be added behind a collapsible directive option? And we could use the prompt option for the details summary.

agriyakhetarpal commented 5 months ago

Not sure if this helps, and I might also be trying to breathe life into a discussion that's already quite old, but at least for the making-things-collapsible aspect, I managed to wrap the directive with a dropdown directive with the sphinx-design Sphinx extension which I think is really neat. It can be tried out here:

https://pywavelets--741.org.readthedocs.build/en/741/regression/wavelet.html

xref: https://github.com/PyWavelets/pywt/pull/741