docs: convert notebooks to jupytext scripts

[jo-mueller]

Fixes #604
Fixes #632

Rebased on #609

Edit: I also added a small piece of code into the conf.py which will clean up any existing .zarr files in the source folders written by previous executions of the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.09%. Comparing base (94eaf20) to head (7acfa25).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #610   +/-   ##
=======================================
  Coverage   87.09%   87.09%           
=======================================
  Files          17       17           
  Lines        2526     2526           
=======================================
  Hits         2200     2200           
  Misses        326      326           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jo-mueller]

@jni is that roughly how it is done over at napari? In VSCode, it's relatively easy to spawn these scripts from jupyter notebooks. It's probably equally easy to turn them into markdown files with executable python code blocks.

[jni]

is that roughly how it is done over at napari?

Yes! Jupytext allows many formats, .py with comments is one, md with python blocks is another. It's a matter of preference which one is preferred, and I guess it depends on the balance of narrative vs code.

You're probably missing a whole bunch of dependencies to get napari windows to spawn, I think this is the most important one:

https://github.com/napari/shared-workflows/blob/200f011f642fd89598422aa14d361113a9bd8059/.github/workflows/build_docs.yml#L76-L80

[jni]

Seems to be working fine!

It will be nice in follow-up PRs to add visualisation with napari, but I think it's best to do that later since this build is working. I spot-checked a couple of pages to make sure that the output was the same.

[jo-mueller]

It will be nice in follow-up PRs to add visualisation with napari, but I think it's best to do that later since this build is working.

Agree! Depending on who shows up later today on the napari-ome-zarr-py call, I'll probably merge it later today 👍

[jo-mueller]

@jni @will-moore @kevinyamauchi could i have eyes here once more? Some more changes here since the last time I updated this PR:

• updated all jupytext documents
• excluded the files from the tests (turned out pytest also ran these as part of the tests, but maybe that's not what we want)
• added a code snippet that deletes all .zarr files inside the docs folder before building the docs so we don't run into file-location-not-empty issues.

I guess it would be nice to merge this before doing more updates elsewhere otherwise updating this along the way will be a bit of a pain ^^"

[will-moore]

Docs built fine, with just one warning:

/Users/wmoore/Desktop/ZARR/ome-zarr-py/docs/source/advanced/transforms/index.md:: WARNING: toctree contains reference to nonexisting document 'advanced/transforms/reading_scenes' [etoc.ref] [docutils]

Pages look good and certainly nicer to have .py files rather than .ipynb.

However, I think it is nice to have these files run as part of the tests. That should help keeping them valid and up to date?

👍