Turning this into draft until it actually works

🤩 🤩 🤩

I have not been able to build the docs locally due to some latex issue I'm having.

They're very difficult to build locally - also takes a long time to build. In general I'd say it's not worth it. But if you do want to (and are on linux) then I found I was able to successfully do it by following this dockerfile: https://github.com/matplotlib/mpl-docker/blob/master/Dockerfile (or I usppose you could use that dockerfile)

Thanks @ianhi! I'll see if I'm more lucky with this dockerfile, otherwise I'll rely on the CI

There is also this: https://matplotlib.org/stable/devel/dependencies.html#additional-external-dependencies

ooooh - @martinRenou you know what, a PR to sphinx-gallery enabling automatically interactive examples would probably be the most high impact jupyterlite docs PR you could make. Because then all https://matplotlib.org/stable/gallery/index would suddenly be runnable in the browser.

There would also be a much shorter feedback cycle as the docs builds wouldn't take nearly as long. If you are interested in that - or in adding it to an existing (but smaller) gallery you feel free to try it out on https://github.com/ianhi/mpl-point-clicker where the docs build is significantly faster

See also: sphinx-gallery/sphinx-gallery#927

Building this locally and using python -m http.server to serve it I get 404s for

http://localhost:8000/users/lite/repl/index.html?kernel=python&code=%20import%20matplotlib.pyplot%20as%20plt%20import%20numpy%20as%20np%20x%20=%20np.linspace(0,%202%20*%20np.pi,%20200)%20y%20=%20np.sin(x)%20fig,%20ax%20=%20plt.subplots()%20ax.plot(x,%20y)%20plt.show()

It looks like the issue is that the what ever is formatting the URL expects to be at the top level, but is actually a level down.

Changing the URL in the iframe to src="/lite/repl/index.html?kernel=python&code= import matplotlib.pyplot as plt import numpy as np x = np.linspace(0, 2 * np.pi, 200) y = np.sin(x) fig, ax = plt.subplots() ax.plot(x, y) plt.show()" (by poking at it interactively in the browser) I can get it to load 🎉, however then it has the issue that the new lines are not preserved so it gives you a syntax error.

@tacaswell it should be possible to pass multiple &code= params, each corresponding to one line.

@jtpio is there a way to keep the line breaks so that the whole code is in just one cell?

Normally it can be encoded and contain new lines. For example with the demo site:

https://jupyterlite.github.io/demo/repl/?kernel=python&toolbar=1&code=import%20matplotlib.pyplot%20as%20plt%0Aimport%20numpy%20as%20np%0Ax%20=%20np.linspace(0,%202%20*%20np.pi,%20200)%0Ay%20=%20np.sin(x)%0Afig,%20ax%20=%20plt.subplots()%0Aax.plot(x,%20y)%0Aplt.show()

Thanks! I'll push a PR fixing jupyterlite-sphinx's replite directive

Done in jupyterlite/jupyterlite-sphinx#30

I was finally able to build the Matplotlib docs locally :) With the new jupyterlite-sphinx version it works like a charm!

Making this PR ready to review! Please tell me if you want any changes to be made

I fail to understand why the CI is failing to build de docs. Though I can reproduce locally, make html fails (without a meaningful error message) while calling sphinx-build . build works correctly.

There are many warnings that look like:

WARNING: multiple files found for the document "gallery/animation/animate_decay": ['gallery/animation/animate_decay.py', 'gallery/animation/animate_decay.py.md5', 'gallery/animation/animate_decay.rst', 'gallery/animation/animate_decay.ipynb']
Use '/home/circleci/project/doc/gallery/animation/animate_decay.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/animated_histogram": ['gallery/animation/animated_histogram.py', 'gallery/animation/animated_histogram.py.md5', 'gallery/animation/animated_histogram.rst', 'gallery/animation/animated_histogram.ipynb']
Use '/home/circleci/project/doc/gallery/animation/animated_histogram.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/animation_demo": ['gallery/animation/animation_demo.py', 'gallery/animation/animation_demo.py.md5', 'gallery/animation/animation_demo.rst', 'gallery/animation/animation_demo.ipynb']
Use '/home/circleci/project/doc/gallery/animation/animation_demo.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/bayes_update": ['gallery/animation/bayes_update.py', 'gallery/animation/bayes_update.py.md5', 'gallery/animation/bayes_update.rst', 'gallery/animation/bayes_update.ipynb']
Use '/home/circleci/project/doc/gallery/animation/bayes_update.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/unchained": ['gallery/animation/unchained.py.md5', 'gallery/animation/unchained.ipynb', 'gallery/animation/unchained.rst', 'gallery/animation/unchained.py']
Use '/home/circleci/project/doc/gallery/animation/unchained.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/double_pendulum": ['gallery/animation/double_pendulum.py', 'gallery/animation/double_pendulum.py.md5', 'gallery/animation/double_pendulum.rst', 'gallery/animation/double_pendulum.ipynb']
Use '/home/circleci/project/doc/gallery/animation/double_pendulum.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/dynamic_image": ['gallery/animation/dynamic_image.py', 'gallery/animation/dynamic_image.py.md5', 'gallery/animation/dynamic_image.rst', 'gallery/animation/dynamic_image.ipynb']
Use '/home/circleci/project/doc/gallery/animation/dynamic_image.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/frame_grabbing_sgskip": ['gallery/animation/frame_grabbing_sgskip.py', 'gallery/animation/frame_grabbing_sgskip.rst', 'gallery/animation/frame_grabbing_sgskip.ipynb']
Use '/home/circleci/project/doc/gallery/animation/frame_grabbing_sgskip.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/pause_resume": ['gallery/animation/pause_resume.py', 'gallery/animation/pause_resume.py.md5', 'gallery/animation/pause_resume.rst', 'gallery/animation/pause_resume.ipynb']
Use '/home/circleci/project/doc/gallery/animation/pause_resume.rst' for the build.
WARNING: multiple files found for the document "gallery/animation/rain": ['gallery/animation/rain.py', 'gallery/animation/rain.py.md5', 'gallery/animation/rain.rst', 'gallery/animation/rain.ipynb']

It looks like repllite is dropping some additional files in places that is confusing sphinx?

Is it possible to add ipympl to the jupyterlite environment here? This could easily be many peoples first interaction with matplotlib and it would be a great opportunity to reinforce the fact that matplotlib is in fact interactive. Thinking about this this because I saw: https://twitter.com/blu3r4d0n/status/1502309909811109888

It would be great indeed @ianhi. Should we probably wait for ipywidgets to work in JupyterLab consoles though? So that people don't get confused as to why ipympl doesn't work in the replite. @jtpio had some ideas on improving the replite, making it so that widgets could probably work as well.

Should we probably wait for ipywidgets to work in JupyterLab consoles though?

ahh I forgot about that. Maybe until then it would make sense to use retrolite here. How difficult would be it be to switch the directive?

Not difficult :) We just need to change the directive from replite to retrolite, and we probably need to add a Notebook to the docs.

To summarize, what's remaining before the PR is working and ready:

• : Understand/Fix the CI issue
• : Add ipympl to the deployment, and use retrolite for the Notebook
• : Fix Improve IFrames src  jupyterlite/jupyterlite-sphinx#36

It looks like repllite is dropping some additional files in places that is confusing sphinx?

What really confuses me is that jupyterlite did not even run yet at the point the warnings are showing up. And those files seems to be more related to the Matplotlib docs than JupyterLite? But the weird thing is that those warnings don't seem to show up in other PRs.

When trying this on CI:
https://output.circle-artifacts.com/output/job/3481f984-d9fa-42f6-aab4-f029b2bd34ec/artifacts/0/doc/build/html/index.html

and clicking on the live box, I get:

Outstanding issues:

Can the extension be made read-parallel safe (is it already and we just need declare it?)?

WARNING: the jupyterlite_sphinx extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit
WARNING: doing serial read

There is a veritable wall of errors that look like:

--- Logging error ---
Traceback (most recent call last):
  File "/home/tcaswell/.pybuild/dd311/lib/python3.11/logging/__init__.py", line 1110, in emit
    msg = self.format(record)
          ^^^^^^^^^^^^^^^^^^^
  File "/home/tcaswell/.pybuild/dd311/lib/python3.11/logging/__init__.py", line 953, in format
    return fmt.format(record)
           ^^^^^^^^^^^^^^^^^^
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/traitlets/config/application.py", line 141, in format
    return super().format(record)
           ^^^^^^^^^^^^^^^^^^^^^^
  File "/home/tcaswell/.pybuild/dd311/lib/python3.11/logging/__init__.py", line 687, in format
    record.message = record.getMessage()
                     ^^^^^^^^^^^^^^^^^^^
  File "/home/tcaswell/.pybuild/dd311/lib/python3.11/logging/__init__.py", line 377, in getMessage
    msg = msg % self.args
          ~~~~^~~~~~~~~~~
TypeError: not all arguments converted during string formatting
Call stack:
  File "/home/tcaswell/.virtualenvs/dd311/bin/jupyter-lite", line 8, in <module>
    sys.exit(main())
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/jupyter_core/application.py", line 276, in launch_instance
    return super().launch_instance(argv=argv, **kwargs)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/traitlets/config/application.py", line 982, in launch_instance
    app.start()
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/jupyter_core/application.py", line 265, in start
    self.subapp.start()
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/jupyterlite/app.py", line 217, in start
    super().start()
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/jupyterlite/app.py", line 169, in start
    self.exit(self.lite_manager.doit_run(*self._doit_cmd))
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/jupyterlite/manager.py", line 56, in doit_run
    return runner.run([task, *args])
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/doit_cmd.py", line 294, in run
    return command.parse_execute(args)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/cmd_base.py", line 150, in parse_execute
    return self.execute(params, args)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/cmd_base.py", line 570, in execute
    return self._execute(**exec_params)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/cmd_run.py", line 265, in _execute
    return runner.run_all(self.control.task_dispatcher())
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/runner.py", line 254, in run_all
    self.run_tasks(task_dispatcher)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/runner.py", line 220, in run_tasks
    base_fail = self.execute_task(node.task)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/runner.py", line 176, in execute_task
    return task.execute(self.stream)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/task.py", line 473, in execute
    action_return = action.execute(task_stdout, task_stderr)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/doit/action.py", line 461, in execute
    returned_value = self.py_callable(*self.args, **kwargs)
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/jupyterlite/addons/contents.py", line 25, in <lambda>
    pprint.pformat([str(p[0]) for p in self.file_src_dest]),
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/jupyterlite/addons/contents.py", line 25, in <listcomp>
    pprint.pformat([str(p[0]) for p in self.file_src_dest]),
  File "/home/tcaswell/.virtualenvs/dd311/lib/python3.11/site-packages/jupyterlite/addons/contents.py", line 118, in file_src_dest
    self.log.debug("Already populated", resolved)
Message: 'Already populated'
Arguments: ('/home/tcaswell/source/p/matplotlib/matplotlib/doc/build/html/lite/files/annotation_polar.ipynb',)

It seems to result in a working website, but (locally) fails the build for me.

This seems to add 400K to the main page, but if you click the "try Matplotlib" button it is on the order of 64M and over my local network takes 8-9 s to load! I think we need a warning and note about the size to expect when clicking the button.

I think we need to make the "view the gallery" link needs to be way more obvious. I knew it was there and took me few seconds to find it.

Launching jupyterlab produces a warning about a git extension and costs about 12M and 10s or so. This probably should also be warned?

The notebooks launch with %matplotlib inline at the top, is it possible to change this to %matplotlib widget ?

In jupyterlab there are directories full of .ipynb, but at the toplevel there is a mix of .ipynb, rst, and pickles (?!).

It seems every time a new notebook is opened another ~50-60M of data is pulled. I'm not sure if this is an inherent problem or the cache being disabled by the dev tools (even if "disable cache" is unchecked?).

I'm going to push a rebase.

Hi all and to those subscribed to this PR, I've been interested in getting this effort revived for Matplotlib through https://github.com/jupyterlite/jupyterlite-sphinx/releases/tag/v0.18.0 that we've now released today on 13/01/2025. I've read through this thread fully, and I'm happy to share that most of the problems noticed in jupyterlite-sphinx and the JupyterLite/WASM ecosystem have been more or less resolved at this point :)

Here is a table that contains a short summary of relevant discussions and previous requests in the code review above for easy access, and my comments on them:

@martinRenou, I wish to ask if you're still interested in completing this PR? I would love to supersede it, but wished to ask in advance. If yes, no worries, I would be happy to step back and let you complete it. :)

Additional comments:

• As it was suggested in DOC: Add replite console to the users docs #22634 (comment) that such a REPL would also make sense to add on Matplotlib's brochure site/landing page at https://matplotlib.org//, besides the docs. I think a button similar to the "Try Matplotlib (on binder)" button, but one that says "Try Matplotlib (JupyterLite" or similar could be added there, which would simply open a REPL or a Jupyter Lab environment with Matplotlib installed. I would be happy to take it up.
• Both the Xeus and Pyodide kernels are reasonably mature and stable enough at this point to run Matplotlib without issues, but we should be fine with choosing either of them for this task (probably Xeus is better)

Hi @martinRenou, I hope it is fine to ping you again here? Perhaps you missed my comment above or didn't see this PR show up in your notifications – I've been planning to work on this lately and hope to open a new PR to supersede this, and I have a working draft on my fork via agriyakhetarpal#1 that preserves authorship. If you prefer I don't do this, please let me know, and thanks for your work!

Hi @agriyakhetarpal! First, thanks a ton for your work in jupyterlite-sphinx 🤟🏽, thanks for the detailed comment here, and thanks for taking this PR over!

Happy to close this one and have yours replace it 😃

Thanks for working on this, I'am very excited!

I know that the grant says to drop it into the docs landing page, but I'm wondering if either on https://github.com/matplotlib/mpl-brochure-site (to replace the existing binder link) or the gallery landing page (because it gets way more traffic https://views.scientific-python.org/matplotlib.org/) makes more sense.

🤦‍♀️ Commented on the wrong PR so gonna move this there, sorry

Closing as replaced by #29506