Update event loop documentation for gui_qt deprecation

[tlambert03]

Description

This updates the event loop doc to reflect the deprecation of gui_qt

Type of change

• This change requires a documentation update

[goanpeca]

Thanks for working on this. Couple of typos and an optional suggestion to capitalize typos.

🥇

[tlambert03]

Thanks for the review! Agreed on all accounts

[sofroniewn]

Thanks for this update. I had a brief look at its all looking good to me, but maybe @DragaDoncila can do a thorough read and review. Thanks!!

[Edit: Also @GenevieveBuckley I know you've thought at lot about this too and how to make this as accessible to new comers as possible, maybe you can give it a read over too!!]

[GenevieveBuckley]

Can we shift the section on "Hooking up your own events" (which includes sub-sections on keybindings, mouse events, et) up above the nitty gritty about "The Qt Event Loop".

I actually think it might also be good to move the in-depth Qt Event Loop stuff into a separate markdown file, and just link to it from here for anyone who wants more information. That would make it much clearer that these parts are "explainer" documentation on how things work under the hood. Mixing it in here with the other practical info, like how to make your own keybindings, is very likely to confuse people.

[tlambert03]

I kinda feel like if anything should go in another file, it's the hooking up of custom events (that always felt out of place to me here). The details about the qt event loop are the direct explanation of why you need napari.run sometimes and not other times (which I think you had asked for elsewhere?)

[GenevieveBuckley]

Yeah, these things should get split up.

[GenevieveBuckley]

I think that's a good idea, and it's also a good idea to clearly distinguish (a) which bits of the docs people need to use/type, vs (b) the bits we are explaining so you understand the stuff under the hood better (but we don't generally want new users to try and sprinkle QApplication stuff through their code)

[GenevieveBuckley]

I'd prefer the docs focus on what we do now, and de-emphasize what we used to do.

It's important to give people the info that we no longer need to call %gui qt, but this is probably better distributed in the release notes, on zulip, and twitter, etc.

[tlambert03]

I did try to deemphasize it with the offset, but given the 2 year usage... I kinda thought a lot of people would be asking "what about gui_qt??" So it'd be nice to send them somewhere to answer that

[tlambert03]

(Also not needing %gui qt magic is a different point than this one, which is about napari.gui_qt)

[sofroniewn]

I think this is ok for a transition period, but maybe in 3-6 months we can revisit and update the language a bit

[tlambert03]

yeah, definitely doesn't have to be there forever

[GenevieveBuckley]

Thanks for doing this @tlambert03

[sofroniewn]

Thanks for the review @GenevieveBuckley. I really like the new connecting events section, I think a lot of people will just want to look there!

I think this is pretty close now. Maybe @DragaDoncila can take one more pass and then it will be good to merge

[sofroniewn]

I think this is ok for a transition period, but maybe in 3-6 months we can revisit and update the language a bit

[DragaDoncila]

This looks great to me, and very readable. Just left a few minor proofreading tweaks.

[tlambert03]

This looks great to me, and very readable. Just left a few minor proofreading tweaks.

thank you for the close read!

[codecov]

Codecov Report

Merging #2639 (ccc9215) into master (2a77cbb) will increase coverage by 0.00%.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2639   +/-   ##
=======================================
  Coverage   81.87%   81.88%           
=======================================
  Files         475      476    +1     
  Lines       39475    39492   +17     
=======================================
+ Hits        32322    32339   +17     
  Misses       7153     7153           

Impacted Files	Coverage Δ
napari/layers/image/_image_constants.py	100.00% <0.00%> (ø)
...i/_qt/layer_controls/_tests/test_qt_image_layer.py	100.00% <0.00%> (ø)
napari/_qt/layer_controls/qt_image_controls.py	95.34% <0.00%> (+0.07%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2a77cbb...ccc9215. Read the comment docs.

[sofroniewn]

Thanks for all the reviews here, will merge now