Repository navigation
Adding Binder links to the Matplotlib gallery #11415
Description
Hey all - we recently added a nifty new feature to sphinx-gallery that automatically generates Binder links for each sphinx gallery example. See the sphinx gallery docs as an example:
I think it'd be cool if we had this for Matplotlib (e.g. each example would have a "launch binder" button at the bottom that could open an interactive version of the example for users).
However, there are a few caveats here:
- Matplotlib docs get a ton of users, and this might have unexpected results on
mybinder.orgif a gigantic influx of people happens. At the least, we'd likely hit the per-repo limit of 100 concurrent Binder sessions. - Binder is still in beta (e.g. it won't have 100% uptime, though is pretty close to this, and may occasionally drop off if we have an outage)
That said, it'd be pretty cool if each of our users was one click away from interacting w/ the matplotlib examples on each page.
What do folks think about this? If we're +1 giving it a shot, I can put together a PR activating the Binder links on the matplotlib docs.
Reacted by Jan Eglinger, J Forde, Michaël Defferrard, Ishank Sharma and Agriya Khetarpal
Activity
ImportanceOfBeingErnest commentedon Jun 11, 2018
What happens if the limit is reached? Who maintains mybinder.org; would the use of this feature be within their envisionned use cases?
From the matplotlib side one could make this an experimental feature, like
and see what happens?
choldgraf commentedon Jun 11, 2018
When the limit is reached binder will display a message saying that the limit is reached for the repository. There's a chance that a gigantic influx of traffic would overwhelm the binder servers and the site would go down, though I think this is small. In that case, we'd remove the binder links from the matplotlib docs.
Re: Binder's envisioned use case, I can confirm that interactive documentation is one of the envisioned use-cases, yes :-)
When is the next release planned? One thing we could do is implement this PR at the beginning of a cycle, and then it's only exist in the
/latestURL as a test runImportanceOfBeingErnest commentedon Jun 11, 2018
In general there is of course a problem with those notebooks generated via sphinx-gallery: There is no control over whether a notebook is to be created/linked to by a certain example. This is important because many examples do not run in
%matplotlib inlinemode.So ideally one would have a directive flagg to set whether an example should (not) contain a notebook and even better, whether that example should use
%matplotlib notebookinstead ofinline.This then quickly leads to even more general problems with sphinx-gallery which has no way to hide code/comments/directives from the output.
In that sense one might also question in how far one should provide non-runnable notebooks to users.
jklymak commentedon Jun 11, 2018
Binder doesn't appear to work with
%matplotlib notebook. What examples don't work ininline? We should proabbly start noting that in the example somewhere. A flag would be cool, if there is an easy way to impliment. Not sure what metadata we can enter into the examples as they are...ImportanceOfBeingErnest commentedon Jun 11, 2018
Well obviously all examples from the sections "Animation", "Widgets" and "Embedding" and I suppose others as well which use
.draggable()or similar stuff.Currently none. Everything written in those files appears in the output, like e.g.
# sphinx_gallery_thumbnail_number = 18in the constrained_layout guide.What's important really is the question: What would weight more,
I'm personally undecided here, but those points may help people come to a conclusion.
choldgraf commentedon Jun 11, 2018
Some quick thoughts:
%matplotlib notebook. Which example didn't work for you @jklymak ?jklymak commentedon Jun 11, 2018
JavaScript output is disabled in JupyterLabcholdgraf commentedon Jun 11, 2018
ah - I think that just means that an extension hasn't been enabled for JupyterLab on that Binder build. It works with the Noteboook UI
jklymak commentedon Jun 11, 2018
I just followed the links. No sure what the Notebook UI is.
FWIW, I'm not 100% against this, but I think most users would be better served by downloading the code and running locally versus running in a remote instance. At some point they are going to want to run matplotlib locally, unless we are trying to send people to binder as a one-stop shop for data analysis. I'm not seeing the benefit of making this run remotely.
timhoffm commentedon Jun 11, 2018
While generally it would be nice to be able to tinker with the examples online, I'm sceptical that we should hook to binder in it's current state.
A feature that's not yet reliably working is creating frustration for the user. That would have to be sorted out before.
ImportanceOfBeingErnest commentedon Jun 11, 2018
I do see the point of letting people run examples on the fly. This has something to do with being inviting and inclusive. People visiting matplotlib.org can directly try out how great this works by running some example and changing the color to "red" - "Oh wow, this is easy, I need that for my project."
... and that is exactly the problem when it comes to this feature only working sometimes or not at all when choosing a non-compatible example. Then it's more "Oh, this doesn't work, I can't even change the color to "red"; let's take some other library instead."
Maybe a whitelist like @timhoffm just mentions is a good start; One could advertise a couple of examples to try out on the main page and make sure those are running fine.
choldgraf commentedon Jun 11, 2018
a few thoughts:
pip install matplotliband never know where the examples are located on their machine). I think a lot more people would click on interactive links on the web.sgskipshould work fine in the Binder environment, provided that the repo is set up with the same environment that sphinx-gallery+CircleCI uses when it runs the examples(full disclosure here - I'm on the sphinx gallery team as well as the Binder team, so we could probably make some additions to one or another project if it'd be valuable here)
jklymak commentedon Jun 11, 2018
Users must run some code locally, at some point in their careers. Presumably some of it is cut and paste from the examples, and/or downloaded from the examples pages. I'm not seeing how going to binder to run the example is better than doing it locally if I want to play with the examples, unless I don't already have a python/matplotlib environment installed. But even if I didn't, I'm not getting the long-term use case for a newbie to start using binder. Why should we, as a package, be guiding people there?
tacaswell commentedon Jun 11, 2018
I am 👍 on this in principle. Reducing the friction of 'let me play with this' to clicking a link is definitely a good thing!
Is ipympl installed in the binder images? If so
%matplotlib widgetshould work and give you interactive figures under jupyter lab.We do run all of the examples as part of building the docs so we know that they are at least valid python and produce reasonable output. The best way to get feedback on which versions of the notebooks work is to open them up and get user feedback on what is broken!
16 remaining items
tacaswell commentedon Feb 9, 2023
This is also related to #22634
github-actions commentedon Jul 19, 2024
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!
agriyakhetarpal commentedon Jan 13, 2025
Hi all – apologies for commenting on an issue that's been around for almost seven years, but I've posted an update on #22634 that was linked above. That PR aims to add an interactive REPL for Matplotlib's docs homepage running via Pyodide/JupyterLite and WebAssembly, and this issue deserves to receive the surrounding context as well: the combination of Sphinx-Gallery through its JupyterLite integration, and its underlying Sphinx extension (
jupyterlite-sphinx) are pretty stable at this point and should overall allow replacing Binder with notebooks that can run Matplotlib with in-browser computation, avoiding server costs.To address #11415 (comment), it is possible to download the notebooks with Sphinx-Gallery. Also, it is theoretically possible to disable a few examples for JupyterLite through Sphinx-Gallery's integrations based on an
sgskiplabel (though, maybe disabling only under JupyterLite and not elsewhere needs to be a feature request or something?).After all, one can expect that it would be useful for both docstring-based API examples that showcase functionality and for the galleries, even if it's on an experimental basis and users are warned that certain notebooks might not work. It is to be noted that
scikit-learnhas had this integration already for their docs' notebooks and they have been maintaining it so far, to the point of Pyodide/WASM as an officially supported platform: scikit-learn/scikit-learn#23727All in all, if this item is still in the ambit, I would be happy to put together a PR. :)
Here are some links to contemporary interactive documentation efforts in the ecosystem for Scientific Python projects:
jupyterlite-sphinxnumpy/numpy#26745