search

PyWavelets / pywt

PyWavelets - Wavelet Transforms in Python
http://pywavelets.readthedocs.org
MIT License
1.97k stars 460 forks source link

Tracking issue for adding interactive documentation #706

Open agriyakhetarpal opened 3 months ago

agriyakhetarpal commented 3 months ago

Description

This is an issue to collect tasks for adding interactive documentation to PyWavelets via JupyterLite kernels/notebooks.

Proposal

Additional comments

The intermediate step would mean that the .whl files would have to be downloaded manually using wget or curl first (a helper script can be created for this) and pointed to the Pyodide-pip interpreter for installation.

rgommers commented 3 months ago

Add CI jobs to run nightly builds of Pyodide wheels (or on every push to master, rather?),

Every push to master would be better; this package moves very slowly so more than that is a bit wasteful.

while configuring versioning to include git hashes or dates

That may be simplified by this just-merged Meson feature: https://github.com/mesonbuild/meson/commit/524a66116b38a65210b7516781d26ed6efb690b9. It'll only be available once 1.4.0 comes out. You could already try locally though whether you can make that work. Note that it would need a .py script rather than the version.sh in the docs, otherwise things won't work on Windows.

agriyakhetarpal commented 3 months ago

Thanks, a 1.4.0 non-RC release for Meson should be out in a week or so when we should be able to do this. A .py script would work nicely too.

I am more concerned about how we would make Read the Docs work with what we are intending to do – I suppose only the process of the implementation can tell what things end up being feasible.

rgommers commented 3 months ago

It's purely client-side, so probably fine on RTD. Switching to GitHub Pages would also be pretty straightforward if needed.

rgommers commented 3 months ago

Investigate where to upload wasm32 wheels (needs an external index that accepts emscripten_X_Y_wasm32 platform tags)

I opened https://github.com/scientific-python/upload-nightly-action/issues/75 to request access to upload to https://anaconda.org/scientific-python-nightly-wheels/repo.

rgommers commented 3 months ago

Add CI jobs to run nightly builds of Pyodide wheels (or on every push to master, rather?)

I'll note that that anaconda.org bucket cleans up nightlies older than 30 days. So how about on every push to master and every 25 days, to be safe?

agriyakhetarpal commented 3 months ago

I'll note that that anaconda.org bucket cleans up nightlies older than 30 days. So how about on every push to master and every 25 days, to be safe?

Yes, that should be fair enough – we would want at least one wheel being uploaded before other ones get cleaned up

agriyakhetarpal commented 3 months ago

Next step is actually getting started with interactive documentation. We already have the usage examples – how should we go ahead? Should I convert them to notebooks as I mentioned above?

rgommers commented 3 months ago

Guess we're getting closer, 4 out of 7 done. I'm starting to prepare the 1.6.0 release. I think we can probably get the "Try Examples" in before that is final (in 2 weeks or so).

rgommers commented 3 months ago

We already have the usage examples – how should we go ahead? Should I convert them to notebooks as I mentioned above?

It is not necessary to convert them to notebooks. The jupyterlite-sphinx extension should be able to work with any regular examples in docstrings. I suggest adding that extension first, seeing what works with it and what doesn't using the PyWavelets 1.5.0 shipped in Pyodide, and then fixing things up as needed.

agriyakhetarpal commented 3 months ago

Guess we're getting closer, 4 out of 7 done. I'm starting to prepare the 1.6.0 release. I think we can probably get the "Try Examples" in before that is final (in 2 weeks or so).

Just adding a comment here to update things: I assume this has been checked out and #731 should now bring v1.6.0 with some new examples. The Emscripten and Pyodide versions are not decoupled at the time of writing, so we won't have v1.6.0 WASM wheels until there is a new version of Pyodide, but it should be okay since there have been no previous API changes as discussed earlier. I have updated the checklist to showcase the most recent scenario. The next task to check off would be to keep investigating the CORS headers issue. We recently merged https://github.com/jupyterlite/jupyterlite-sphinx/pull/161, and a release for jupyterlite-sphinx should be coming soon – after that, we can remove the :button_text: input from all examples (which shall fix the issue we had faced, mentioned in the PR linked above).

agriyakhetarpal commented 1 month ago

From https://github.com/PyWavelets/pywt/pull/737#discussion_r1589741088, the "Usage Examples" section is now being worked on; it can be targeted for a v1.6.1 milestone/release.

agriyakhetarpal commented 1 month ago

Note to self: https://github.com/jupyterlite/jupyterlite/issues/461 might be useful; I hope it is added to the Pyodide kernel. It might be possible to write a custom JupyterLite kernel for this such as https://github.com/jobovy/jupyterlite-repl-prerun.