Use markdown and Jupyter notebooks in doc pages by jo-mueller · Pull Request #548 · ome/ome-zarr-py

jo-mueller · 2026-03-10T12:42:00Z

Fixes #536

codecov · 2026-03-10T12:51:47Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.83%. Comparing base (0fc60fd) to head (8c49daf).
⚠️ Report is 218 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #548      +/-   ##
==========================================
+ Coverage   86.80%   86.83%   +0.02%     
==========================================
  Files          14       14              
  Lines        1857     1861       +4     
==========================================
+ Hits         1612     1616       +4     
  Misses        245      245

☔ 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 · 2026-03-11T11:24:35Z

@will-moore this would be my take on how I'd structure the docs going forward.

I essentially broke all the examples from the python.rst file into separate jupyter notebooks that are actually executed on build 👍

docs: add myst outputs to ignored files [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci docs: delete legacy markdown viewing tutorial deps: add sphinx-design to doc deps deps: add sphinx-book-theme to doc dependencies [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci Delete write_hcs_plate.md docs: fix link docs: remove jupyter execute artefacts from tracked files test: remove faulty notebooks from build test: remove read notebook Delete view_ome_zarr.ipynb ci: push through errors Revert "Delete view_ome_zarr.ipynb" This reverts commit 7635186. Revert "test: remove read notebook" This reverts commit 49379c6. docs: remove read notebook ci: ignore false positives in codespell do not show viewer docs: delete view notebook deps[docs]: Add ome-zarr-py to deps deps[docs]: update local version update deps fix build [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci Revert "docs: delete view notebook" This reverts commit 93ff591. [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci deps: add napari-ome-zarr to deps remove view notebook Revert "docs: remove read notebook" This reverts commit 0be2723.

will-moore · 2026-03-12T14:29:23Z

Could you add info to the main README or docs/README/ on how to build the docs locally?
And is it possible to have the docs deploy somewhere from a PR? (not essential, but nice)!

jo-mueller · 2026-03-12T18:37:27Z

@will-moore

And is it possible to have the docs deploy somewhere from a PR? (not essential, but nice)!

That'll have to be done by the readthedocs maintainers of the RTD project. If you have access there, you can add me as a maintainer under Setup > Maintainers. Otherwise, the respective setting is under Settings at the very bottom:

Could you add info to the main README or docs/README/ on how to build the docs locally?

Good idea!

jo-mueller · 2026-03-12T18:38:32Z

What I didn't get to work was to show how to use (napari-) ome-zarr in a notebook that would include a viewer screenshot - maybe there are some restrictions regarding notebooks executed on the RTD CI and GUI applications? 🤔

jo-mueller · 2026-03-13T08:35:47Z

@will-moore Also, I just realized: PR builds are already enabled 😅

Just hit the link in the actions:

joshmoore · 2026-03-13T09:09:59Z

Not necessarily related to this PR but a few points by looking through the webpage:

Generally some graphics would help, which leads me to wonder if we embed the validator and/or vizarr in various places
Left-hand menu: s/OME-NGFF/OME-Zarr/

docs: ome-ngff -> ome-zarr

for more information, see https://pre-commit.ci

jo-mueller · 2026-03-13T21:47:03Z

Thanks for the feedback! @joshmoore I added a markdown document with the validator embedded as an iFrame, that's actually pretty cool to use right out of the built pages :)

I also played with having napari screenshots directly here in the demo notebooks, but the RTD seems to have an issue with GIU applications in notebooks, as it seems. Or maybe it's the async rendering? 🤔

jo-mueller · 2026-03-17T13:21:28Z

@will-moore anything you think I should add here?

will-moore · 2026-03-17T14:20:00Z

I'm seeing [] in a bunch of places:

Ah - is this the output from the code above?

jo-mueller · 2026-03-17T15:08:13Z

Ah - is this the output from the code above?

Yep and I think it kind of makes sense. If compute=False is passed to the function, the writer will not execute but return a list of delayed objects. If compute=True, everything is written, all jobs are finished so the list is empty.

Edit: In the future, I could imagine that the delayed_objects becomes an attribute of the NGffImage class introduced in #515 In that case, we wouldn't need the return

for more information, see https://pre-commit.ci

into glow-up-docs

jo-mueller · 2026-03-17T16:01:12Z

@will-moore build is looking green on my end so all cross-references seem to resolve correctly 👍

for more information, see https://pre-commit.ci

will-moore

Looks great, thanks! 👍

jo-mueller added 2 commits March 10, 2026 13:40

docs: Use jupyter notebooks and mystmd in doc pages

87b8694

docs: reorganize doc pages into separate jupyter notebook tutorials

b37ffa0

jo-mueller force-pushed the glow-up-docs branch from f3949eb to 491ef9a Compare March 11, 2026 21:50

jo-mueller marked this pull request as ready for review March 11, 2026 21:50

jo-mueller mentioned this pull request Mar 12, 2026

Add image class #515

Merged

6 tasks

will-moore reviewed Mar 13, 2026

View reviewed changes

Comment thread docs/source/howtos/build_custom_pyramid.ipynb Outdated

docs: ome-ngff -> ome-zarr

3bc81a5

docs: ome-ngff -> ome-zarr

jo-mueller force-pushed the glow-up-docs branch from 8ac9c15 to 3bc81a5 Compare March 13, 2026 20:41

jo-mueller and others added 6 commits March 13, 2026 22:41

chore: rename folders

21e6dcb

docs: add demo on how to open images

7dc43b6

docs: fix reference

9a7d26c

[pre-commit.ci] auto fixes from pre-commit.com hooks

ad006cc

for more information, see https://pre-commit.ci

chore: fix typo

857f4a7

docs: move viewing up in TOC

719147c

will-moore reviewed Mar 17, 2026

View reviewed changes

Comment thread docs/source/basic/write_image.ipynb Outdated

will-moore reviewed Mar 17, 2026

View reviewed changes

Comment thread docs/source/basic/write_image.ipynb Outdated

jo-mueller and others added 2 commits March 17, 2026 16:53

docs: fix links and descriptions

a121117

[pre-commit.ci] auto fixes from pre-commit.com hooks

03d9edd

for more information, see https://pre-commit.ci

jo-mueller added 2 commits March 17, 2026 16:57

docs: fix cross-reference

02a124a

Merge branch 'glow-up-docs' of https://github.com/jo-mueller/ome-zarr-py

5b88bc0

into glow-up-docs

jo-mueller changed the title ~~WIP: Glow up docs~~ Glow up docs Mar 17, 2026

jo-mueller changed the title ~~Glow up docs~~ Use markdown and Jupyter notebooks in doc pages Mar 17, 2026

docs: fix link target

2d9423b

will-moore reviewed Mar 17, 2026

View reviewed changes

Comment thread docs/source/basic/write_labels.ipynb

will-moore reviewed Mar 17, 2026

View reviewed changes

Comment thread docs/source/advanced/build_custom_pyramid.ipynb Outdated

will-moore reviewed Mar 17, 2026

View reviewed changes

Comment thread docs/source/advanced/build_custom_pyramid.ipynb Outdated

will-moore reviewed Mar 17, 2026

View reviewed changes

Comment thread docs/source/explanation/multiscale_pyramids.md Outdated

jo-mueller and others added 3 commits March 17, 2026 23:26

chore: typos and other minor fixes

b39a0c1

[pre-commit.ci] auto fixes from pre-commit.com hooks

0b4bd60

for more information, see https://pre-commit.ci

chore: fix broken link

8c49daf

jo-mueller requested a review from will-moore March 19, 2026 09:23

will-moore approved these changes Mar 19, 2026

View reviewed changes

jo-mueller merged commit aacce7b into ome:master Mar 19, 2026
13 checks passed

jo-mueller deleted the glow-up-docs branch April 10, 2026 12:37

Uh oh!

Conversation

jo-mueller commented Mar 10, 2026

Uh oh!

codecov Bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jo-mueller commented Mar 11, 2026

Uh oh!

will-moore commented Mar 12, 2026

Uh oh!

jo-mueller commented Mar 12, 2026

Uh oh!

jo-mueller commented Mar 12, 2026

Uh oh!

jo-mueller commented Mar 13, 2026

Uh oh!

Uh oh!

joshmoore commented Mar 13, 2026

Uh oh!

jo-mueller commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jo-mueller commented Mar 17, 2026

Uh oh!

will-moore commented Mar 17, 2026

Uh oh!

Uh oh!

Uh oh!

jo-mueller commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jo-mueller commented Mar 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

will-moore left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov Bot commented Mar 10, 2026 •

edited

Loading

jo-mueller commented Mar 13, 2026 •

edited

Loading

jo-mueller commented Mar 17, 2026 •

edited

Loading