Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork7.9k
DOC: Add a JupyterLite-powered REPL to the Matplotlib documentation's landing page, and enable interactive galleries#29506
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Uh oh!
There was an error while loading.Please reload this page.
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 uson gitter for real-time discussion.
For details on testing, writing docs, and our review process, please seethe developer guide
We strive to be a welcoming and open project. Please follow ourCode of Conduct.
agriyakhetarpal commentedJan 23, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
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 wellhttps://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 docshere It seems numpy 1.25.2 was pulled there |
Thanks for the feedback,@martinRenou! I pinned NumPy to <2 ind8d63da untilemscripten-forge/recipes#1766 can be resolved.
I was surprised because many of the recent PRs that were auto-merged inhttps://github.com/emscripten-forge/recipes target other branches, such ashttps://github.com/emscripten-forge/recipes/tree/emscripten-3.1.58 orhttps://github.com/emscripten-forge/recipes/tree/emscripten-3.1.73, so I was confused that thehttps://repo.mamba.pm/emscripten-forge channel was still at 3.1.45. It's clearer after I've learned that other channels, such ashttps://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 beforehttps://matplotlib.org/stable/gallery/index.html#lines-bars-and-markers in3faa465, 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: |
story645 commentedJan 23, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
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 |
martinRenou commentedJan 24, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
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. |
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
| @@ -0,0 +1,7 @@ | |||
| { | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Why is there ajupyter-lite.json andjupyter_lite_config.json? These seem redundantly (or at least non-descriptively) named.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
The JupyterLite CLI is atraitlets based app, sojupyter_lite_config.json follows the naming convention as other apps, likevoila.json orjupyter_server_config.json. It is indeed for build time configuration (when running the JupyterLite CLI, for example withjupyter lite build).
jupyter-lite.json is for runtime configuration when loading the page. It is similar to thepage_config.json used in JupyterLab.
Agree this can be confusing. Maybe JupyterLite could also support loadingpage_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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 itcould be negligible for all I know.
agriyakhetarpalJan 24, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 withhtml-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 theDEVDOCS andis_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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 onhttps://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 withf0d4de4 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. |
agriyakhetarpal commentedJan 24, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
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 |
martinRenou commentedJan 27, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
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. |
agriyakhetarpal commentedJan 28, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
We now have another error in [LiteBuildApp]ERROR| [lite] [post_build] [jupyterlite-xeus] [ERR]expectedstr,bytesoros.PathLikeobject,notNoneTypeTraceback (mostrecentcalllast):File"/home/circleci/.local/lib/python3.12/site-packages/doit/doit_cmd.py",line294,inrunreturncommand.parse_execute(args)^^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/cmd_base.py",line150,inparse_executereturnself.execute(params,args)^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/cmd_base.py",line570,inexecutereturnself._execute(**exec_params)^^^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/cmd_run.py",line265,in_executereturnrunner.run_all(self.control.task_dispatcher())^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/runner.py",line254,inrun_allself.run_tasks(task_dispatcher)File"/home/circleci/.local/lib/python3.12/site-packages/doit/runner.py",line213,inrun_tasksnode=task_dispatcher.generator.send(node)^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/control.py",line629,in_dispatcher_generatornext_step=node.step()^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/control.py",line336,instepreturnnext(self.generator)^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/control.py",line345,in_funcforvalueindecorated(*args,**kwargs):^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/control.py",line473,in_add_tasknew_tasks=generate_tasks(to_load,task_gen,ref.__doc__)^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/loader.py",line390,ingenerate_tasksfortask_dict,x_docinflat_generator(gen_result,gen_doc):^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/doit/loader.py",line27,inflat_generatorforitemingen:^^^File"/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_core/manager.py",line138,in_delayed_gatheryieldfrom_gather()File"/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_core/manager.py",line131,in_gatherraiseerrorFile"/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_core/manager.py",line123,in_gatherfortaskingetattr(addon,attr)(self):^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_xeus/add_on.py",line141,inpost_buildyieldfromself.copy_kernels_from_prefix()File"/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_xeus/add_on.py",line193,incopy_kernels_from_prefixyieldfromself.copy_kernel(kernel_dir,kernel_wasm,kernel_js,kernel_data)File"/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_xeus/add_on.py",line303,incopy_kernelyieldfromself.pack_prefix(kernel_dir=kernel_dir)File"/home/circleci/.local/lib/python3.12/site-packages/jupyterlite_xeus/add_on.py",line328,inpack_prefixpack_kwargs["file_filters"]=pkg_file_filter_from_yaml(DEFAULT_CONFIG_PATH)^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^File"/home/circleci/.local/lib/python3.12/site-packages/empack/file_patterns.py",line86,inpkg_file_filter_from_yamlwithopen(path)aspack_config_file:^^^^^^^^^^TypeError:expectedstr,bytesoros.PathLikeobject,notNoneType[LiteBuildApp]Exitingapplication:jupyter |
Uh oh!
There was an error while loading.Please reload this page.
PR summary
Why is this change necessary?
This PR adds an (experimental)interactive REPL enabled bythe JupyterLite project viathe
jupyterlite-sphinxSphinx extension'sReplite (.. 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