docs: Auto-generated examples gallery

[GenevieveBuckley]

Currently there are a ton of great examples in the repo that are effectively invisible to anyone looking at the main documentation page at https://pyapp-kit.github.io/magicgui/

This PR uses mkdocs-gallery to automatically generate an examples gallery for the docs website. This provides some nice features, including:

• Buttons for users to download code in python file or jupyter notebooks format
• The CI will build this along with the rest of the docs, using the same mkdocs commands as before
• The code is executed to produce screenshots, so if your examples code somehow falls out of sync with the library syntax, you should get an error and warning your about that.
• if somebody adds a new example script, it is also automatically added to the website - no more accidentally forgetting to add new pages to the mkdocs nav table of contents!

I've previously done something similar for the napari-threedee project napari-threedee/napari-threedee#99. If you'd like to play around with that live on their website, it's here: https://napari-threedee.github.io/generated/gallery/

Here's a screenshot of the proposed new examples page for magicgui, running locally on my laptop. There are a lot of examples, so I've tried to group them into meaningful themes.

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: -0.60% ⚠️

Comparison is base (6e6f0da) 88.20% compared to head (2caf03d) 87.61%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #571      +/-   ##
==========================================
- Coverage   88.20%   87.61%   -0.60%     
==========================================
  Files          39       39              
  Lines        4528     4528              
==========================================
- Hits         3994     3967      -27     
- Misses        534      561      +27     

see 3 files with indirect coverage changes

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

[GenevieveBuckley]

There's a couple of weird things I want to make you aware of:

• I had to move the example scripts into the docs folder. mkdocs-gallery say you can have them located outside it, but I had trouble with that. I don't think this is a big deal.
• There are two files I'm not actually executing the code for
  • The values_dialog.py user input example blocks code execution until the user responds. That doesn't work well when auto-generating the docs examples on CI, so I've made that file contain text cells formatted to look like code. That way nothing executes with mkdocs, and I'm just pointing to a static png image of the output.
  • I also couldn't execute the jupyter notebook example easily (my screenshot scraper doesn't work well with the jupyter notebook backend. Possibly this could be improved in the future?). Again, here I've made that file contain text cells formatted to look like code. That way nothing executes with mkdocs, and I'm just pointing to a static png image of the output.
• The output from the class_methods.py example looks like something has gone wrong - but when I run this locally I also get a blank Qt window with nothing in it. Possibly we could add a text label or something to the Qt window in that demo so the output doesn't look quite as weird.
• I don't know how to control the order the examples appear in very well. The section order appears to be controlled by folder name alphabetically (so if you want them in a specific order, I guess you could add numbers to the start of the directory names).

[tlambert03]

😍🤩

Thank you!! Will have a closer look through your comments soon

[tlambert03]

I've had a look (and pushed a couple changes, so pull again before working on it more). I really love it, thanks so much.

The only change I'm not thrilled about are the napari examples, and basically anything where the # %% syntax had to be added to the python source files. I find them rather messy to read through, and feel like they kinda ruin the example files themselves (in favor of only ever looking at them in the built website). I know it's a tradeoff, but i'd like to think about those a bit, or perhaps fall back to a hybrid mixture of examples.

But, I won't think about it too long, this is awesome as is and i want to get it in :)

[GenevieveBuckley]

Thank you for figuring out the CI and formatting!

Two more things I noticed:

1. The napari example auto-generated screenshots don't show the magicgui dock widget. I don't know why, taking a screenshot manually seems to work. Maybe this doesn't matter too much, your gif movies are much better demonstrations in any case.
2. The progress bar examples don't show the progress bar in the auto-generated screenshots either. This is more understandable, since it doesn't appear until you click the "Run" button, which obviously isn't happening in the auto-generated docs. Again, maybe not an actual problem, just wanted to mention it.

[GenevieveBuckley]

The only change I'm not thrilled about are the napari examples, and basically anything where the # %% syntax had to be added to the python source files. I find them rather messy to read through, and feel like they kinda ruin the example files themselves (in favor of only ever looking at them in the built website). I know it's a tradeoff, but i'd like to think about those a bit, or perhaps fall back to a hybrid mixture of examples.

That's a reasonable hesitation. I've fiddled with things a bit, and I think things are a bit nicer now.

This affects four files:

1. values_dialog.py
2. The magicgui jupyter notebook example
3. napari example - image arithmetic
4. napari example - parameter sweep

1 and 2 are because it's hard to run those scripts in the automatic CI.
3 and 4 are because you want to combine code with text eplanation (but don't like the jupytext formatting that leaves a lot of # symbols on all the text lines).

First I tried to see if we could just add markdown files side by side along with the python example files, but it looks like that is not supported. If that's potentially a big long term issue, we could ask if there are any future plans to support that behaviour in mkdocs-gallery.

For now, what I've done is to move as much content as possible into the docstrings at the top of the file. Any code we actually want to execute goes below that. That at least cuts down on the number of lines prefaced with # when you download and look at the plain text.

You do still have to have at least one # %% line at the very bottom, otherwise you get a big "broken" text image for that example in the gallery. But if an empty # %% is there at the bottom of the file, it is treated like an empty code cell, and everything is fine.

Still a small compromise, but perhaps one we can live with for now. I personally think it helps address those concerns a bit.

[tlambert03]

let's get this in. I think the end result is great.

there are still a number of things i'm not crazy about, but can address them in follow up PRs. some notes so I remember:

• the gallery plugin appears to be regenerating all of the examples every time any file changes, so using mkdocs serve for realtime editing of the docs becomes much less useful.
• the gallery plugin appears to be using threading somehow, and sending an interrupt signal with control-C no longer shuts down the mkdocs serve live server. this is a big pain... and the only way I've been able to stop it is to kill the entire terminal process. It makes me a bit concerned with the stability/innards of the plugin itself.
• I do have general concerns about the mkdocs-gallery plugin itself. in addition to the odd mkodcs serve behavior, it has a mkdocs deprecation warning from something that changed way back in Jun, 2021, so i wonder how actively maintained it is... and it's not a "popular" plugin (by stars) so perhaps has more rough edges.
• i do prefer the current napari examples (with the docs at the top)... but it comes at the cost of code duplication between the code in the docstrings and the code itself, which now has the risk of going out of sync... Perhaps includes/snippets could be used here, but I'll look into that later.

[tlambert03]

thanks @GenevieveBuckley!