DOC: Add a JupyterLite-powered REPL to the Matplotlib documentation's landing page, and enable interactive galleries #29506
Conversation
There was a problem hiding this comment.
Thank you for opening your first PR into Matplotlib!
If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks.
You can also join us on gitter for real-time discussion.
For details on testing, writing docs, and our review process, please see the developer guide
We strive to be a welcoming and open project. Please follow our Code of Conduct.
|
I'm facing a problem here locally with an environment from Full stack traceForcing |
|
What you are having here is weird. A fresh deployment we have on the official jupyterlite-xeus docs works well https://jupyterlite-xeus.readthedocs.io/en/latest/lite/lab/index.html
This is the env file used: https://github.com/jupyterlite/xeus/blob/main/docs/environment.yml You can see the logs for building the docs here It seems numpy 1.25.2 was pulled there |
|
Thanks for the feedback, @martinRenou! I pinned NumPy to <2 in d8d63da until emscripten-forge/recipes#1766 can be resolved.
I was surprised because many of the recent PRs that were auto-merged in https://github.com/emscripten-forge/recipes target other branches, such as https://github.com/emscripten-forge/recipes/tree/emscripten-3.1.58 or https://github.com/emscripten-forge/recipes/tree/emscripten-3.1.73, so I was confused that the https://repo.mamba.pm/emscripten-forge channel was still at 3.1.45. It's clearer after I've learned that other channels, such as https://prefix.dev/channels/emscripten-forge-dev exist, too.
Thanks, @story645! The grant doesn't necessarily mention a specific location – any page is fine to me. I don't have access to that Plausible Analytics page; could you please export a brief view of the stats? Of course, I trust your judgement, though. I proposed the same idea of a "Try with JupyterLite" button on the brochure site in #22634 (comment), although I opine that we should keep the existing Binder button next to it and not remove it right now, as JupyterLite is going to stay experimental for some time. I've moved this console to a section before https://matplotlib.org/stable/gallery/index.html#lines-bars-and-markers in 3faa465, so that it is relatively at the top of the page and not hidden away at the end of the page where readers need to scroll away to. |
|
That page should be public but this is the important part:
Stable index only gets about 24.5k views.
I'd put it under the tagging note -> does it work in a drop down so folks can collapse it if they don't need it? |
|
Build fails: |
|
Put this on the call today to try and avoid sending @agriyakhetarpal on a page changing goose chase (sorry if you started already 😓). Consensus was leave it on |
Weird that it's looking for the empack config there. Did you activate the micromamba env properly?
Adding a note that with the current setup, it's only when the user explicitly clicks on the button that the JupyterLite page loads. |
| @@ -0,0 +1,7 @@ | ||
| { |
There was a problem hiding this comment.
Why is there a jupyter-lite.json and jupyter_lite_config.json? These seem redundantly (or at least non-descriptively) named.
There was a problem hiding this comment.
I've always been confused about this myself. One is for the CLI, one is for the JupyterLite frontend. The naming is pretty bad.
There was a problem hiding this comment.
The JupyterLite CLI is a traitlets based app, so jupyter_lite_config.json follows the naming convention as other apps, like voila.json or jupyter_server_config.json. It is indeed for build time configuration (when running the JupyterLite CLI, for example with jupyter lite build).
jupyter-lite.json is for runtime configuration when loading the page. It is similar to the page_config.json used in JupyterLab.
Agree this can be confusing. Maybe JupyterLite could also support loading page_config.json files so users could choose a different name for the file?
For more information: https://jupyterlite.readthedocs.io/en/stable/howto/configure/config_files.html
| @@ -767,6 +780,23 @@ def js_tag_with_cache_busting(js): | ||
| 1), | ||
| ] | ||
|
|
||
| # JupyterLite config |
There was a problem hiding this comment.
Is there a way this can be disabled by default and enabled by a flag? This could be set on CI and in release mode. I'm not sure we want to be paying the build costs locally for every developer. But since the build failed, I'm not sure exactly how large that build time cost is, so it could be negligible for all I know.
There was a problem hiding this comment.
The build time cost is around ~15 seconds for me locally, which seems negligible in comparison to the rest of the docs build – I've been building with html-noplot at this time, so it would even lesser of a fraction with CI builds which would be longer.
But to answer whether this can be disabled, I can check for the DEVDOCS and is_release_build constants so that this is avoided on local builds, as this concern was also raised from the perspective of downstream packagers in the older PR #22634. It could make debugging a build that's failing in CI a bit of a pain, though.
There was a problem hiding this comment.
Well, let's see how long it ends up taking first.
No worries, and thanks for prioritising this in the call, @story645! I would have been happy to attend the Matplotlib Documentation Meeting myself and seek feedback from folks, but unfortunately, based on https://scientific-python.org/calendars/, it's past midnight for me. I hope there can be more times for the meetings that can cater to the SEA region, someday. I've kept the REPL on the index page with f0d4de4 as suggested, and yes, as Martin mentioned, the REPL loads only when someone clicks on the "Try it" button. As an additional safeguard, the URL parameter for the iframe also has |
I haven't yet. I'm not sure if we'll want to switch the CircleCI config to using a micromamba environment, if we were to activate it before the Maybe it looks in the |
Ah sorry I thought you were using the I'm wondering where empack installed its config file in there, maybe it was installed in the wrong place, or it's looking in the wrong place. |
|
I think it's placing it in an appropriate location: but we aren't in a virtual environment, and |
|
That said, I feel |
|
I created a PR to do that for |
Thanks! empack 5.0.4 is out now on PyPi, if you want to try. For the conda package you may need to wait another hour. |
|
We now have another error in [LiteBuildApp] ERROR | [lite] [post_build] [jupyterlite-xeus] [ERR] expected str, bytes or os.PathLike object, not NoneType
Traceback (most recent call last):
File "/home/circleci/.local/lib/python3.12/site-packages/doit/doit_cmd.py", line 294, in run
return command.parse_execute(args)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/cmd_base.py", line 150, in parse_execute
return self.execute(params, args)
^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/cmd_base.py", line 570, in execute
return self._execute(**exec_params)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/cmd_run.py", line 265, in _execute
return runner.run_all(self.control.task_dispatcher())
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/runner.py", line 254, in run_all
self.run_tasks(task_dispatcher)
File "/home/circleci/.local/lib/python3.12/site-packages/doit/runner.py", line 213, in run_tasks
node = task_dispatcher.generator.send(node)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/control.py", line 629, in _dispatcher_generator
next_step = node.step()
^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/control.py", line 336, in step
return next(self.generator)
^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/control.py", line 345, in _func
for value in decorated(*args, **kwargs):
^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/control.py", line 473, in _add_task
new_tasks = generate_tasks(to_load, task_gen, ref.__doc__)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/loader.py", line 390, in generate_tasks
for task_dict, x_doc in flat_generator(gen_result, gen_doc):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/doit/loader.py", line 27, in flat_generator
for item in gen:
^^^
File "/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_core/manager.py", line 138, in _delayed_gather
yield from _gather()
File "/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_core/manager.py", line 131, in _gather
raise error
File "/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_core/manager.py", line 123, in _gather
for task in getattr(addon, attr)(self):
^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_xeus/add_on.py", line 141, in post_build
yield from self.copy_kernels_from_prefix()
File "/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_xeus/add_on.py", line 193, in copy_kernels_from_prefix
yield from self.copy_kernel(kernel_dir, kernel_wasm, kernel_js, kernel_data)
File "/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_xeus/add_on.py", line 303, in copy_kernel
yield from self.pack_prefix(kernel_dir=kernel_dir)
File "/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_xeus/add_on.py", line 328, in pack_prefix
pack_kwargs["file_filters"] = pkg_file_filter_from_yaml(DEFAULT_CONFIG_PATH)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/circleci/.local/lib/python3.12/site-packages/empack/file_patterns.py", line 86, in pkg_file_filter_from_yaml
with open(path) as pack_config_file:
^^^^^^^^^^
TypeError: expected str, bytes or os.PathLike object, not NoneType
[LiteBuildApp] Exiting application: jupyter |
PR summary
Why is this change necessary?
This PR adds an (experimental) interactive REPL enabled by the JupyterLite project via the
jupyterlite-sphinxSphinx extension's Replite (.. replite::) directive to the Matplotlib documentation's landing page, therefore displaying an interactive showcase for users who would like to try out Matplotlib without needing to install anything on their machine.What problem does it solve?
This is the first step of an initiative that aims to interactive documentation elements for Scientific Python projects' websites, therefore making it easier for newcomers to access (compiled) Scientific Python projects.
Please see more about it here: Scientific Python awarded CZI grant to improve communications infrastructure & accessibility
xref:
What is the reasoning for this implementation?
At the moment, the plan for adding interactive documentation to Matplotlib is three-fold (or two-fold?):
jupyterlite-sphinx'sTryExamplesdirective make docstring-based examples interactive by adding a button to enable mini-notebooks that embed the API-based examples. However, I don't know if this applies to a project like Matplotlib, as the API reference here seldom seems to contain full-fledged/self-contained, and end-to-end examples, unlike NumPy or SciPy, and the galleries display most of the functionality of Matplotlib.This PR is the first part of the plan.
Tip
The previous PR for these changes, #22634, made it through a few rounds of code review. I have tried to address those previous review comments here through further changes here, and a summary of the previous review(s) is available in this comment: #22634 (comment)
Note
Though Sphinx-Gallery's integration has been disabled for now to be added in a subsequent PR, the gallery is accessible through the JupyterLite deployment that is generated alongside Matplotlib's documentation build as a result of
jupyterlite-sphinx.PR checklist